funolio-agent 1.0.75 → 1.1.65

package/dist/codex-app-server-manager.js

@@ -4,17 +4,26 @@ exports.__codexAppServerTestUtils = exports.CodexAppServerManager = void 0;
 exports.getCodexAppServerManager = getCodexAppServerManager;
 exports.runCodexAppServerTurnForTest = runCodexAppServerTurnForTest;
 const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
 const runtime_context_1 = require("./runtime-context");
 const sync_cli_config_1 = require("./mcp/sync-cli-config");
+const managed_process_registry_1 = require("./managed-process-registry");
 const LOCAL_ONLY_ERROR = 'Codex app-server manager is local_desktop only';
+const CODEX_APP_SERVER_WARM_TIMEOUT_MS = 10_000;
 const DEFAULT_CODEX_SETTINGS = {
-    reasoningEffort: 'none',
+    reasoningEffort: 'low',
     reasoningSummary: 'detailed',
     personality: 'friendly',
     serviceTier: 'fast',
     sandboxPolicy: 'danger-full-access',
     approvalPolicy: 'never',
 };
+const VALID_CODEX_REASONING_EFFORTS = new Set(['low', 'medium', 'high', 'xhigh']);
+const VALID_CODEX_REASONING_SUMMARIES = new Set(['auto', 'concise', 'detailed', 'none']);
+const VALID_CODEX_PERSONALITIES = new Set(['friendly', 'pragmatic']);
+const VALID_CODEX_SERVICE_TIERS = new Set(['fast', 'flex']);
+const VALID_CODEX_SANDBOX_POLICIES = new Set(['read-only', 'workspace-write', 'danger-full-access']);
+const VALID_CODEX_APPROVAL_POLICIES = new Set(['untrusted', 'on-failure', 'on-request', 'never']);
 let _manager = null;
 let _prepareCodexCliConfigChain = Promise.resolve();
 function delay(ms) {
@@ -33,6 +42,48 @@ function throwIfNotLocalDesktop(runtimeMode) {
 function sessionKey(conversationId, botId) {
     return `${conversationId}::${botId}`;
 }
+function hasProcessExited(child) {
+    const exitCode = child?.exitCode;
+    const signalCode = child?.signalCode;
+    return ((exitCode !== null && exitCode !== undefined)
+        || (signalCode !== null && signalCode !== undefined));
+}
+function collectProcessRestartReasons(session, cwd, requestedEnvFingerprint, expectedThreadId) {
+    const reasons = [];
+    if (session.cwd !== cwd)
+        reasons.push('cwd_mismatch');
+    if (session.closed || hasProcessExited(session.child))
+        reasons.push('process_unhealthy');
+    if (session.envFingerprint !== requestedEnvFingerprint)
+        reasons.push('env_mismatch');
+    if (expectedThreadId && session.threadId && session.threadId !== expectedThreadId) {
+        reasons.push('incompatible_thread_request');
+    }
+    return reasons;
+}
+function buildWarmTimeoutError(timeoutMs) {
+    const err = new Error(`codex app-server warm session timed out after ${Math.floor(timeoutMs / 1000)}s`);
+    err.code = 'CODEX_APP_SERVER_WARM_TIMEOUT';
+    err.name = 'CodexAppServerWarmTimeoutError';
+    return err;
+}
+function withWarmTimeout(promise, timeoutMs, onTimeout) {
+    let timeout = null;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+            try {
+                onTimeout();
+            }
+            finally {
+                reject(buildWarmTimeoutError(timeoutMs));
+            }
+        }, timeoutMs);
+    });
+    return Promise.race([promise, timeoutPromise]).finally(() => {
+        if (timeout)
+            clearTimeout(timeout);
+    });
+}
 function createEventLog() {
     return {
         schema: 'funolio.codex-app-server.event-log@1',
@@ -55,13 +106,77 @@ function serializeEventLog(eventLog) {
 function normalizeDetail(text) {
     return String(text || '').replace(/\s+/g, ' ').trim();
 }
-function scrubCodexAppServerEnv(baseEnv, extraEnv) {
+function isImportantLiveDetail(text) {
+    return /\b(ERROR|Error|failed|failure|Exit code:\s*[1-9]|authentication|rate limit|timeout|timed out|denied|unauthorized)\b/i.test(text);
+}
+function isGeneratedOrDependencyNoise(text) {
+    return (/\.map(?::|\b)/i.test(text)
+        || /(?:^|[\\/])node_modules[\\/]/i.test(text)
+        || /[\\/]?\.cargo[\\/]registry[\\/]/i.test(text)
+        || /src-tauri[\\/]gen[\\/]schemas/i.test(text)
+        || /\bpackage-lock\.json\b/i.test(text)
+        || /\bCargo\.lock\b/i.test(text)
+        || /\bdist[\\/]assets[\\/][^ ]+\.(?:js|css)\b/i.test(text));
+}
+function looksLikeMinifiedBlob(text) {
+    if (text.length < 1000)
+        return false;
+    const whitespaceCount = (text.match(/\s/g) || []).length;
+    const punctuationCount = (text.match(/[{}()[\],;:=]/g) || []).length;
+    return whitespaceCount / text.length < 0.08 && punctuationCount > 80;
+}
+function looksLikeRawSourceLine(text) {
+    return /^\s*(const|let|function|import|export|type|interface|class|return|if |for |while |case |await |async |try |catch|}\)|}}|\]|\)|\{)\b/.test(text);
+}
+function looksLikeSearchOutput(text) {
+    return /^(?:src|packages|prisma|scripts|public|app|C:\\|\.github)[\\/].*:\d+/.test(text)
+        || /^\s*[\w.\-/\\]+:\d+/.test(text);
+}
+function truncateLiveDetail(text, maxLength) {
+    if (text.length <= maxLength)
+        return text;
+    return `${text.slice(0, maxLength)} ...[truncated raw output]`;
+}
+function prepareLiveDetailForUser(activeTurn, detail, source) {
+    const normalized = normalizeDetail(detail);
+    if (!normalized)
+        return null;
+    if (source === 'status') {
+        return truncateLiveDetail(normalized, 600);
+    }
+    if (isImportantLiveDetail(normalized)) {
+        return truncateLiveDetail(normalized, 900);
+    }
+    if (isGeneratedOrDependencyNoise(normalized) || looksLikeMinifiedBlob(normalized)) {
+        return null;
+    }
+    if (looksLikeSearchOutput(normalized)) {
+        const count = activeTurn.liveDetailCategoryCounts.get('search_output') || 0;
+        activeTurn.liveDetailCategoryCounts.set('search_output', count + 1);
+        if (count >= 25)
+            return null;
+        return truncateLiveDetail(normalized, 500);
+    }
+    if (normalized.length > 1000) {
+        return null;
+    }
+    if ((source === 'command_output' || source === 'file_output') && looksLikeRawSourceLine(normalized)) {
+        const count = activeTurn.liveDetailCategoryCounts.get('raw_source_line') || 0;
+        activeTurn.liveDetailCategoryCounts.set('raw_source_line', count + 1);
+        if (count >= 40)
+            return null;
+    }
+    return truncateLiveDetail(normalized, 600);
+}
+function scrubCodexAppServerEnv(baseEnv, extraEnv, sessionKey) {
     const env = {};
     for (const [key, value] of Object.entries(baseEnv)) {
         if (value == null)
             continue;
         if (key === 'CODEX_THREAD_ID')
             continue;
+        if (key === 'FUNOLIO_TOOL_TODO_ID')
+            continue;
         env[key] = value;
     }
     for (const [key, value] of Object.entries(extraEnv)) {
@@ -69,11 +184,18 @@ function scrubCodexAppServerEnv(baseEnv, extraEnv) {
             continue;
         env[key] = value;
     }
+    if (sessionKey) {
+        const marker = (0, managed_process_registry_1.getMarkerEnv)(sessionKey);
+        for (const [k, v] of Object.entries(marker)) {
+            env[k] = v;
+        }
+    }
     return env;
 }
+const VOLATILE_ENV_KEYS = new Set(['FUNOLIO_TOOL_TODO_ID', 'FUNOLIO_MANAGED_SESSION']);
 function computeEnvFingerprint(env) {
     return JSON.stringify(Object.entries(env)
-        .filter(([, value]) => typeof value === 'string')
+        .filter(([key, value]) => typeof value === 'string' && !VOLATILE_ENV_KEYS.has(key))
         .sort(([a], [b]) => a.localeCompare(b)));
 }
 function buildCodexAppServerToolEnv(input) {
@@ -83,14 +205,28 @@ function buildCodexAppServerToolEnv(input) {
         env.FUNOLIO_TOOL_ACTOR_ID = actorId;
     if (input.projectId !== undefined && input.projectId !== null)
         env.FUNOLIO_TOOL_PROJECT_ID = String(input.projectId);
-    if (input.todoTaskId !== undefined && input.todoTaskId !== null)
-        env.FUNOLIO_TOOL_TODO_ID = String(input.todoTaskId);
     return env;
 }
+function buildTurnMcpToolEnv(sessionEnv, currentTodoTaskId) {
+    const toolEnv = {};
+    for (const k of ['FUNOLIO_TOOL_ACTOR_ID', 'FUNOLIO_TOOL_PROJECT_ID']) {
+        if (sessionEnv[k])
+            toolEnv[k] = sessionEnv[k];
+    }
+    if (currentTodoTaskId !== undefined && currentTodoTaskId !== null) {
+        toolEnv.FUNOLIO_TOOL_TODO_ID = String(currentTodoTaskId);
+    }
+    return toolEnv;
+}
 function extractLatestUserText(messages) {
+    const renderContent = (content) => (typeof content === 'string'
+        ? content
+        : content.map((part) => (part.type === 'text'
+            ? part.text
+            : `[image:${part.mimeType};${Math.ceil((part.data?.length || 0) * 0.75)} bytes]`)).join('\n'));
     const lastMessage = messages.length > 0 ? messages[messages.length - 1] : null;
     if (lastMessage?.role === 'user') {
-        return lastMessage.content || '';
+        return renderContent(lastMessage.content);
     }
     if (messages.length === 0)
         return '';
@@ -99,27 +235,51 @@ function extractLatestUserText(messages) {
             : message.role === 'assistant' ? 'ASSISTANT'
                 : message.role === 'tool' ? `TOOL (${message.toolName || 'tool'})`
                     : String(message.role || 'MESSAGE').toUpperCase();
-        return `${label}:\n${message.content || ''}`;
+        return `${label}:\n${renderContent(message.content)}`;
     });
     return rendered.join('\n\n');
 }
 function buildCodexAppServerInput(messages) {
-    return [
-        {
-            type: 'text',
-            text: extractLatestUserText(messages),
-        },
-    ];
+    const lastMessage = messages.length > 0 ? messages[messages.length - 1] : null;
+    const content = lastMessage?.role === 'user' ? lastMessage.content : null;
+    // If the last user message has multimodal content, build image + text blocks
+    if (content && typeof content !== 'string') {
+        const blocks = [];
+        for (const part of content) {
+            if (part.type === 'text') {
+                blocks.push({ type: 'text', text: part.text });
+            }
+            else if (part.type === 'image' && part.data) {
+                blocks.push({
+                    type: 'image',
+                    url: `data:${part.mimeType || 'image/png'};base64,${part.data}`,
+                });
+            }
+        }
+        if (blocks.length > 0)
+            return blocks;
+    }
+    // Fallback: text-only
+    return [{ type: 'text', text: extractLatestUserText(messages) }];
 }
 function buildTurnUsage(tokenUsage) {
     const last = tokenUsage?.last;
     if (!last || typeof last !== 'object')
         return undefined;
-    const inputTokens = Number(last.inputTokens || 0) + Number(last.cachedInputTokens || 0);
+    // token.txt Change 1: keep inputTokens sum + add breakdown.
+    const fresh = Number(last.inputTokens || 0);
+    const cacheRead = Number(last.cachedInputTokens || 0);
+    const inputTokens = fresh + cacheRead;
     const outputTokens = Number(last.outputTokens || 0) + Number(last.reasoningOutputTokens || 0);
     if (!Number.isFinite(inputTokens) || !Number.isFinite(outputTokens))
         return undefined;
-    return { inputTokens, outputTokens };
+    return {
+        inputTokens,
+        inputTokensFresh: fresh,
+        inputTokensCacheCreation: 0,
+        inputTokensCacheRead: cacheRead,
+        outputTokens,
+    };
 }
 function extractThreadId(payload) {
     const id = payload?.thread?.id ?? payload?.threadId ?? null;
@@ -169,6 +329,16 @@ function describeStartupStatus(params) {
     const error = typeof params?.error === 'string' && params.error.trim() ? ` (${params.error.trim()})` : '';
     return `${name}: ${status}${error}`;
 }
+function extractItemId(params) {
+    const id = params?.item?.id ?? params?.itemId ?? null;
+    return typeof id === 'string' && id.trim() ? id.trim() : null;
+}
+function extractAgentMessagePhase(params) {
+    if (params?.item?.type !== 'agentMessage')
+        return null;
+    const phase = params?.item?.phase ?? null;
+    return typeof phase === 'string' && phase.trim() ? phase.trim().toLowerCase() : null;
+}
 function describeItemProgress(method, params) {
     if (!params?.item || typeof params.item !== 'object')
         return null;
@@ -183,14 +353,94 @@ function describeItemProgress(method, params) {
     const prefix = method === 'item/started' ? 'Started' : 'Completed';
     return `${prefix} ${itemType}${label ? `: ${label}` : ''}${status}`;
 }
+/**
+ * Build a structured tool event from a Codex app-server item/started or
+ * item/completed notification, when the item type represents a tool-like
+ * operation. Returns null for non-tool items (e.g. agent_message, reasoning).
+ *
+ * Recognized tool item types:
+ *   - command_execution → shell command (PTY exec)
+ *   - file_change       → file edit / write / delete
+ *   - mcpToolCall       → MCP tool invocation
+ *   - applyPatch        → patch apply
+ */
+function buildToolEventFromItem(kind, params) {
+    const item = params?.item;
+    if (!item || typeof item !== 'object')
+        return null;
+    const itemType = typeof item.type === 'string' ? item.type : '';
+    const toolItemTypes = new Set([
+        'command_execution',
+        'file_change',
+        'mcpToolCall',
+        'mcp_tool_call',
+        'applyPatch',
+        'apply_patch',
+    ]);
+    if (!toolItemTypes.has(itemType))
+        return null;
+    const toolName = (typeof item.name === 'string' && item.name)
+        || (typeof item.toolName === 'string' && item.toolName)
+        || (typeof item.serverName === 'string' && item.serverName)
+        || itemType;
+    const toolCallId = (typeof item.id === 'string' && item.id)
+        || (typeof item.itemId === 'string' && item.itemId)
+        || `codex-${itemType}-${Date.now()}`;
+    const event = {
+        kind,
+        toolName,
+        toolCallId,
+    };
+    if (kind === 'call') {
+        if (item.command || item.input || item.arguments || item.path || item.changes) {
+            event.arguments = {
+                ...(item.command ? { command: item.command } : {}),
+                ...(item.input ? { input: item.input } : {}),
+                ...(item.arguments ? item.arguments : {}),
+                ...(item.path ? { path: item.path } : {}),
+                ...(item.changes ? { changes: item.changes } : {}),
+            };
+        }
+    }
+    else {
+        // result
+        const output = (typeof item.output === 'string' && item.output)
+            || (typeof item.stdout === 'string' && item.stdout)
+            || (typeof item.result === 'string' && item.result)
+            || '';
+        if (output)
+            event.output = output;
+        const status = typeof item.status === 'string' ? item.status.toLowerCase() : '';
+        event.isError = status === 'failed' || status === 'error' || !!item.error;
+    }
+    return event;
+}
 function normalizeCodexSettings(settings) {
+    const reasoningEffort = String(settings?.reasoningEffort || '').trim().toLowerCase();
+    const reasoningSummary = String(settings?.reasoningSummary || '').trim().toLowerCase();
+    const personality = String(settings?.personality || '').trim().toLowerCase();
+    const serviceTier = String(settings?.serviceTier || '').trim().toLowerCase();
+    const sandboxPolicy = String(settings?.sandboxPolicy || '').trim().toLowerCase();
+    const approvalPolicy = String(settings?.approvalPolicy || '').trim().toLowerCase();
     return {
-        reasoningEffort: String(settings?.reasoningEffort || DEFAULT_CODEX_SETTINGS.reasoningEffort),
-        reasoningSummary: String(settings?.reasoningSummary || DEFAULT_CODEX_SETTINGS.reasoningSummary),
-        personality: String(settings?.personality || DEFAULT_CODEX_SETTINGS.personality),
-        serviceTier: String(settings?.serviceTier || DEFAULT_CODEX_SETTINGS.serviceTier),
-        sandboxPolicy: String(settings?.sandboxPolicy || DEFAULT_CODEX_SETTINGS.sandboxPolicy),
-        approvalPolicy: String(settings?.approvalPolicy || DEFAULT_CODEX_SETTINGS.approvalPolicy),
+        reasoningEffort: VALID_CODEX_REASONING_EFFORTS.has(reasoningEffort)
+            ? reasoningEffort
+            : DEFAULT_CODEX_SETTINGS.reasoningEffort,
+        reasoningSummary: VALID_CODEX_REASONING_SUMMARIES.has(reasoningSummary)
+            ? reasoningSummary
+            : DEFAULT_CODEX_SETTINGS.reasoningSummary,
+        personality: VALID_CODEX_PERSONALITIES.has(personality)
+            ? personality
+            : DEFAULT_CODEX_SETTINGS.personality,
+        serviceTier: VALID_CODEX_SERVICE_TIERS.has(serviceTier)
+            ? serviceTier
+            : DEFAULT_CODEX_SETTINGS.serviceTier,
+        sandboxPolicy: VALID_CODEX_SANDBOX_POLICIES.has(sandboxPolicy)
+            ? sandboxPolicy
+            : DEFAULT_CODEX_SETTINGS.sandboxPolicy,
+        approvalPolicy: VALID_CODEX_APPROVAL_POLICIES.has(approvalPolicy)
+            ? approvalPolicy
+            : DEFAULT_CODEX_SETTINGS.approvalPolicy,
     };
 }
 function buildThreadSandbox(sandboxPolicy) {
@@ -213,6 +463,27 @@ function buildTurnSandboxPolicy(sandboxPolicy) {
             return { type: 'dangerFullAccess' };
     }
 }
+/**
+ * SHA-256 of the params that, together, define a unique Codex thread.
+ * If any of these inputs differ between warm-up and Send, the warmed
+ * thread is stale and must be invalidated so a fresh one is created
+ * with the current settings. systemPrompt is hashed rather than stored
+ * directly to avoid keeping a second copy of a potentially large string.
+ */
+function computeThreadBootstrapFingerprint(opts) {
+    const settings = normalizeCodexSettings(opts.codexSettings);
+    const parts = [
+        opts.systemPrompt || '',
+        opts.model || '',
+        settings.approvalPolicy,
+        settings.sandboxPolicy,
+        settings.personality,
+        settings.reasoningEffort,
+        settings.serviceTier,
+        opts.resumeSessionId || '',
+    ];
+    return (0, crypto_1.createHash)('sha256').update(parts.join('\u0000')).digest('hex');
+}
 function buildApprovalResponse(method, params) {
     switch (method) {
         case 'item/commandExecution/requestApproval':
@@ -253,56 +524,328 @@ class CodexAppServerManager {
         this.prepareCliConfig = deps.prepareCliConfig || defaultPrepareCliConfig;
         this.logInfo = deps.logInfo || ((message) => console.log(message));
         this.logWarn = deps.logWarn || ((message) => console.warn(message));
-        this.clientInfo = deps.clientInfo || { name: 'funolio-agent', version: '1.0.74' };
+        this.clientInfo = deps.clientInfo || { name: 'funolio-agent', version: '1.1.5' };
     }
-    async runTurn(opts) {
+    async warmSession(opts) {
         throwIfNotLocalDesktop(opts.runtimeMode);
         const key = sessionKey(opts.conversationId, opts.botId);
         const requestedEnv = scrubCodexAppServerEnv(process.env, buildCodexAppServerToolEnv({
             botId: opts.botId,
             botName: opts.botName,
             projectId: opts.projectId,
-            todoTaskId: opts.currentTodoTaskId,
-        }));
+        }), key);
         const requestedEnvFingerprint = computeEnvFingerprint(requestedEnv);
+        const wantsThreadBootstrap = typeof opts.systemPrompt === 'string' && opts.systemPrompt.length > 0;
+        let hiddenPrimerCompleted = false;
+        const requestedBootstrapFingerprint = wantsThreadBootstrap
+            ? computeThreadBootstrapFingerprint({
+                systemPrompt: opts.systemPrompt,
+                model: opts.model,
+                codexSettings: opts.codexSettings,
+                resumeSessionId: opts.resumeSessionId,
+            })
+            : null;
         let session = this.sessions.get(key);
-        const expectedThreadId = opts.forceFreshSession ? null : (opts.resumeSessionId || null);
         if (session
-            && (opts.forceFreshSession
-                || session.cwd !== opts.cwd
+            && (session.cwd !== opts.cwd
                 || session.closed
-                || session.envFingerprint !== requestedEnvFingerprint
-                || (expectedThreadId && session.threadId && session.threadId !== expectedThreadId))) {
+                || session.envFingerprint !== requestedEnvFingerprint)) {
             this.closeSession(key);
             session = undefined;
         }
+        if (session
+            && wantsThreadBootstrap
+            && session.threadId
+            && session.threadBootstrapFingerprint
+            && session.threadBootstrapFingerprint !== requestedBootstrapFingerprint) {
+            session.threadId = null;
+            session.threadBootstrapFingerprint = null;
+            session.bootstrapPromise = null;
+            session.warmPromise = null;
+            session.warmRequestedAtMs = null;
+            session.warmReadyAtMs = null;
+            session.bootstrapGeneration++;
+        }
+        const reusedExistingSession = !!session;
         if (!session) {
-            session = await this.createSession(key, opts.cwd, requestedEnv);
+            session = await this.createSession(key, opts.cwd, requestedEnv, opts.currentTodoTaskId);
             this.sessions.set(key, session);
         }
+        // Fast path: session exists, handshake already complete, AND either
+        // (a) the caller didn't ask for a thread bootstrap, or (b) the thread
+        // is already bootstrapped with the current fingerprint.
+        const bootstrapAlreadyCorrect = !wantsThreadBootstrap
+            || (!!session.threadId && session.threadBootstrapFingerprint === requestedBootstrapFingerprint);
+        if (reusedExistingSession
+            && !session.warmPromise
+            && !session.warmReadyAtMs
+            && session.readyResolved
+            && bootstrapAlreadyCorrect) {
+            (0, managed_process_registry_1.markReused)(key);
+            return {
+                reusedExistingSession,
+                readyAgeMs: Math.max(0, this.now() - session.lastUsedAtMs),
+                sessionId: session.threadId || null,
+                hiddenPrimerCompleted: false,
+            };
+        }
+        if (!session.warmPromise && !session.warmReadyAtMs) {
+            session.warmRequestedAtMs = this.now();
+            session.warmPromise = withWarmTimeout((async () => {
+                await session.readyPromise;
+                if (session.closed) {
+                    throw new Error('Codex app-server warm session closed before it was ready');
+                }
+                if (wantsThreadBootstrap && !session.threadId && !session.bootstrapPromise) {
+                    session.bootstrapPromise = this.bootstrapWarmThread(session, opts, requestedBootstrapFingerprint);
+                    const primerMessages = Array.isArray(opts.primerMessages) && opts.primerMessages.length > 0
+                        ? opts.primerMessages
+                        : null;
+                    if (primerMessages) {
+                        session.bootstrapPromise = session.bootstrapPromise.then(async () => {
+                            if (!session || session.closed || !session.threadId)
+                                return;
+                            try {
+                                await this.runTurnInternal(session, {
+                                    runtimeMode: opts.runtimeMode,
+                                    conversationId: opts.conversationId,
+                                    botId: opts.botId,
+                                    botName: opts.botName,
+                                    cwd: opts.cwd,
+                                    systemPrompt: opts.systemPrompt || '',
+                                    messages: primerMessages,
+                                    model: opts.model || null,
+                                    projectId: opts.projectId,
+                                    currentTodoTaskId: opts.currentTodoTaskId,
+                                    codexSettings: {
+                                        ...(opts.codexSettings || {}),
+                                        reasoningEffort: 'low',
+                                        reasoningSummary: 'none',
+                                    },
+                                    resumeSessionId: null,
+                                }, {
+                                    skipBootstrapWait: true,
+                                    suppressSendPathLog: true,
+                                });
+                                hiddenPrimerCompleted = true;
+                                this.logInfo(`[cli-warm] codex hidden primer completed threadId=${JSON.stringify(session.threadId)}`);
+                            }
+                            catch (err) {
+                                this.logWarn(`[cli-warm] codex hidden primer failed: ${err?.message || String(err)}`);
+                            }
+                        });
+                    }
+                }
+                if (session.bootstrapPromise) {
+                    await session.bootstrapPromise;
+                    session.bootstrapPromise = null;
+                }
+                session.warmReadyAtMs = this.now();
+            })(), opts.timeoutMs ?? CODEX_APP_SERVER_WARM_TIMEOUT_MS, () => this.closeSession(key)).catch((err) => {
+                if (this.sessions.get(key) === session) {
+                    this.closeSession(key);
+                }
+                throw err;
+            });
+        }
+        await session.warmPromise;
+        return {
+            reusedExistingSession,
+            readyAgeMs: session.warmReadyAtMs ? Math.max(0, this.now() - session.warmReadyAtMs) : 0,
+            sessionId: session.threadId || null,
+            hiddenPrimerCompleted,
+        };
+    }
+    /**
+     * Issues thread/start (or thread/resume if resumeSessionId is provided)
+     * during warm-up, populating session.threadId so runTurn can skip the
+     * call. Failure leaves the session with no thread id — runTurn will
+     * retry from scratch via its normal path.
+     */
+    async bootstrapWarmThread(session, opts, fingerprint) {
+        const settings = normalizeCodexSettings(opts.codexSettings);
+        const gen = session.bootstrapGeneration;
+        const startMs = this.now();
+        const BOOTSTRAP_TIMEOUT_MS = 30_000;
+        try {
+            const rpcParams = opts.resumeSessionId
+                ? {
+                    threadId: opts.resumeSessionId,
+                    cwd: opts.cwd,
+                    developerInstructions: opts.systemPrompt || null,
+                    approvalPolicy: settings.approvalPolicy,
+                    sandbox: buildThreadSandbox(settings.sandboxPolicy),
+                    model: opts.model || null,
+                    personality: settings.personality,
+                    modelProvider: 'openai',
+                }
+                : {
+                    cwd: opts.cwd,
+                    developerInstructions: opts.systemPrompt || null,
+                    approvalPolicy: settings.approvalPolicy,
+                    sandbox: buildThreadSandbox(settings.sandboxPolicy),
+                    model: opts.model || null,
+                    personality: settings.personality,
+                    modelProvider: 'openai',
+                    ephemeral: false,
+                };
+            const method = opts.resumeSessionId ? 'thread/resume' : 'thread/start';
+            const response = await Promise.race([
+                this.sendRequest(session, method, rpcParams),
+                new Promise((_, reject) => setTimeout(() => reject(new Error('Thread bootstrap timed out')), BOOTSTRAP_TIMEOUT_MS)),
+            ]);
+            if (session.bootstrapGeneration !== gen)
+                return;
+            session.threadId = extractThreadId(response);
+            session.threadBootstrapFingerprint = fingerprint;
+            this.logInfo(`[cli-warm] codex thread bootstrap completed in ${this.now() - startMs}ms threadId=${JSON.stringify(session.threadId)}`);
+        }
+        catch (err) {
+            if (session.bootstrapGeneration !== gen)
+                return;
+            session.threadId = null;
+            session.threadBootstrapFingerprint = null;
+            this.logWarn(`[cli-warm] codex thread bootstrap failed: ${err?.message || String(err)}`);
+        }
+    }
+    async runTurn(opts) {
+        throwIfNotLocalDesktop(opts.runtimeMode);
+        const key = sessionKey(opts.conversationId, opts.botId);
+        const requestedEnv = scrubCodexAppServerEnv(process.env, buildCodexAppServerToolEnv({
+            botId: opts.botId,
+            botName: opts.botName,
+            projectId: opts.projectId,
+        }), key);
+        const requestedEnvFingerprint = computeEnvFingerprint(requestedEnv);
+        let session = this.sessions.get(key);
+        const expectedThreadId = opts.forceFreshSession ? null : (opts.resumeSessionId || null);
+        const restartReasons = session
+            ? collectProcessRestartReasons(session, opts.cwd, requestedEnvFingerprint, expectedThreadId)
+            : [];
+        if (session && restartReasons.length > 0) {
+            this.logInfo(`[codex-app-server] codex_process_restarted conversationId=${JSON.stringify(opts.conversationId)} botId=${JSON.stringify(opts.botId)} pid=${session.child.pid ?? 'unknown'} reasons=${JSON.stringify(restartReasons)} requestedThreadId=${JSON.stringify(expectedThreadId)} existingThreadId=${JSON.stringify(session.threadId)}`);
+            this.closeSession(key);
+            session = undefined;
+        }
+        // Stale warm-thread invalidation. If warmSession bootstrapped a thread
+        // with a different systemPrompt / model / settings than this turn is
+        // using, the thread is wrong and must be discarded. Keeping the
+        // session + handshake alive; only the threadId is cleared so the
+        // existing "no thread → create one" branch of runTurnInternal fires.
+        if (session && session.threadId && session.threadBootstrapFingerprint) {
+            const currentFingerprint = computeThreadBootstrapFingerprint({
+                systemPrompt: opts.systemPrompt,
+                model: opts.model,
+                codexSettings: opts.codexSettings,
+                resumeSessionId: opts.forceFreshSession ? null : (opts.resumeSessionId || null),
+            });
+            if (currentFingerprint !== session.threadBootstrapFingerprint) {
+                session.threadId = null;
+                session.threadBootstrapFingerprint = null;
+                session.bootstrapPromise = null;
+                session.bootstrapGeneration++;
+            }
+        }
+        if (session?.warmPromise) {
+            try {
+                await session.warmPromise;
+                this.logInfo(`[cli-warm] warm_reused conversationId=${JSON.stringify(opts.conversationId)} botId=${JSON.stringify(opts.botId)} provider="codex-cli" ageMs=${session.warmReadyAtMs ? this.now() - session.warmReadyAtMs : 0}`);
+                session.warmPromise = null;
+                session.warmRequestedAtMs = null;
+                session.warmReadyAtMs = null;
+            }
+            catch {
+                if (this.sessions.get(key) === session) {
+                    this.closeSession(key);
+                }
+                session = undefined;
+            }
+        }
+        else if (session?.warmReadyAtMs) {
+            this.logInfo(`[cli-warm] warm_reused conversationId=${JSON.stringify(opts.conversationId)} botId=${JSON.stringify(opts.botId)} provider="codex-cli" ageMs=${this.now() - session.warmReadyAtMs}`);
+            session.warmPromise = null;
+            session.warmRequestedAtMs = null;
+            session.warmReadyAtMs = null;
+        }
+        if (!session) {
+            this.logInfo(`[cli-warm] send_cold conversationId=${JSON.stringify(opts.conversationId)} botId=${JSON.stringify(opts.botId)} provider="codex-cli"`);
+            session = await this.createSession(key, opts.cwd, requestedEnv, opts.currentTodoTaskId);
+            this.sessions.set(key, session);
+        }
+        else {
+            (0, managed_process_registry_1.markReused)(key);
+            this.logInfo(`[codex-app-server] codex_process_reuse conversationId=${JSON.stringify(opts.conversationId)} botId=${JSON.stringify(opts.botId)} pid=${session.child.pid ?? 'unknown'} forceFreshSession=${opts.forceFreshSession ? 'true' : 'false'} threadId=${JSON.stringify(session.threadId)}`);
+        }
         const run = async () => this.runTurnInternal(session, opts);
         const queued = session.chain.then(run, run);
         session.chain = queued.then(() => undefined, () => undefined);
         return queued;
     }
+    hasActiveSession(conversationId, botId) {
+        const session = this.sessions.get(sessionKey(conversationId, botId));
+        return !!session && !session.closed;
+    }
     closeSessionByConversation(conversationId, botId) {
         this.closeSession(sessionKey(conversationId, botId));
     }
+    closeSessionsByConversation(conversationId) {
+        const prefix = `${conversationId}::`;
+        let closed = 0;
+        for (const key of [...this.sessions.keys()]) {
+            if (key.startsWith(prefix)) {
+                this.closeSession(key);
+                closed++;
+            }
+        }
+        return closed;
+    }
+    closeWarmSessionsByConversation(conversationId) {
+        const prefix = `${conversationId}::`;
+        let closed = 0;
+        for (const [key, session] of [...this.sessions.entries()]) {
+            if (key.startsWith(prefix) && (session.warmPromise || session.warmReadyAtMs)) {
+                this.closeSession(key);
+                closed++;
+            }
+        }
+        return closed;
+    }
+    closeSessionsByBotId(botId) {
+        const suffix = `::${botId}`;
+        for (const key of [...this.sessions.keys()]) {
+            if (key.endsWith(suffix)) {
+                this.closeSession(key);
+            }
+        }
+    }
     closeAll() {
         for (const key of [...this.sessions.keys()]) {
             this.closeSession(key);
         }
     }
+    closeSessionByKey(key) {
+        this.closeSession(key);
+    }
     closeSession(key) {
         const session = this.sessions.get(key);
         if (!session)
             return;
         session.closed = true;
-        try {
-            session.child.kill();
+        session.bootstrapPromise = null;
+        session.bootstrapGeneration++;
+        const pid = session.child.pid;
+        let closeFailed = false;
+        if (pid) {
+            const killResult = (0, managed_process_registry_1.killProcessTreeDetailed)(pid);
+            closeFailed = !killResult.killed || !!killResult.error;
         }
-        catch {
-            // best effort
+        else {
+            try {
+                session.child.kill();
+            }
+            catch {
+                closeFailed = true;
+            }
         }
         for (const pending of session.pendingRequests.values()) {
             pending.reject(new Error('Codex app-server session closed'));
@@ -313,15 +856,26 @@ class CodexAppServerManager {
             session.activeTurn = null;
         }
         this.sessions.delete(key);
+        (0, managed_process_registry_1.unregisterProcess)(key, false, closeFailed);
     }
-    async createSession(key, cwd, env) {
-        await this.prepareCliConfig();
-        const child = this.spawnProcess(process.platform === 'win32' ? 'codex' : 'codex', ['app-server'], {
-            stdio: 'pipe',
-            shell: process.platform === 'win32',
-            windowsHide: true,
-            cwd,
-            env,
+    async createSession(key, cwd, env, currentTodoTaskId) {
+        // Serialize config-write + spawn as an atomic unit through the global
+        // chain so concurrent Codex sessions can't interleave config.toml writes.
+        // Codex reads config.toml at startup to discover MCP servers and their env,
+        // so the write must complete before spawn AND no other write can happen
+        // between this write and the spawned process reading its config.
+        const toolEnv = buildTurnMcpToolEnv(env, currentTodoTaskId);
+        const child = await new Promise((resolve, reject) => {
+            _prepareCodexCliConfigChain = _prepareCodexCliConfigChain.then(async () => {
+                await (0, sync_cli_config_1.syncMcpToCliConfig)('codex-cli', toolEnv);
+                resolve(this.spawnProcess(process.platform === 'win32' ? 'codex' : 'codex', ['app-server'], {
+                    stdio: 'pipe',
+                    shell: process.platform === 'win32',
+                    windowsHide: true,
+                    cwd,
+                    env: env,
+                }));
+            }).catch(reject);
         });
         const session = {
             key,
@@ -338,9 +892,29 @@ class CodexAppServerManager {
             threadId: null,
             readyPromise: Promise.resolve(),
             readyResolved: false,
+            warmPromise: null,
+            warmRequestedAtMs: null,
+            warmReadyAtMs: null,
+            threadBootstrapFingerprint: null,
+            bootstrapPromise: null,
+            bootstrapGeneration: 0,
             closed: false,
             chain: Promise.resolve(),
         };
+        if (child.pid) {
+            this.logInfo(`[codex-app-server] spawned key=${key} pid=${child.pid} cwd=${cwd}`);
+            const keyParts = key.split('::');
+            (0, managed_process_registry_1.registerProcess)({
+                sessionKey: key,
+                provider: 'codex-app-server',
+                conversationId: keyParts[0] || '',
+                botId: keyParts[1] || '',
+                pid: child.pid,
+                cwd,
+                createdAt: new Date(session.createdAtMs).toISOString(),
+                lastUsedAt: new Date(session.lastUsedAtMs).toISOString(),
+            });
+        }
         child.stdout.on('data', (chunk) => {
             this.handleStdout(session, chunk.toString());
         });
@@ -363,10 +937,20 @@ class CodexAppServerManager {
         this.sendNotification(session, 'initialized');
         session.readyResolved = true;
     }
-    async runTurnInternal(session, opts) {
+    syncTurnMcpConfig(session, currentTodoTaskId) {
+        const toolEnv = buildTurnMcpToolEnv(session.env, currentTodoTaskId);
+        _prepareCodexCliConfigChain = _prepareCodexCliConfigChain.then(async () => {
+            await (0, sync_cli_config_1.syncMcpToCliConfig)('codex-cli', toolEnv);
+        });
+        return _prepareCodexCliConfigChain;
+    }
+    async runTurnInternal(session, opts, internalOpts) {
         await session.readyPromise;
         session.lastUsedAtMs = this.now();
+        (0, managed_process_registry_1.updateLastUsed)(session.key);
+        (0, managed_process_registry_1.markTurnStarted)(session.key, 'codex_turn');
         const codexSettings = normalizeCodexSettings(opts.codexSettings);
+        await this.syncTurnMcpConfig(session, opts.currentTodoTaskId);
         const eventLog = createEventLog();
         const completionPromise = new Promise((resolve, reject) => {
             const activeTurn = {
@@ -374,14 +958,20 @@ class CodexAppServerManager {
                 turnId: null,
                 finalContent: '',
                 thinkingText: '',
+                commentaryItemIds: new Set(),
+                commentaryTextByItemId: new Map(),
+                lastCommentaryText: '',
                 done: false,
                 aborted: false,
                 callbackChain: Promise.resolve(),
                 detailFingerprints: new Set(),
+                liveDetailCategoryCounts: new Map(),
                 eventLog,
                 onChunk: opts.onChunk,
+                onCommentary: opts.onCommentary,
                 onThinkingChunk: opts.onThinkingChunk,
                 onDetail: opts.onDetail,
+                onToolEvent: opts.onToolEvent,
                 resolveCompletion: resolve,
                 rejectCompletion: reject,
             };
@@ -405,8 +995,26 @@ class CodexAppServerManager {
         try {
             const requestedThreadId = opts.forceFreshSession ? null : (opts.resumeSessionId || null);
             if (opts.forceFreshSession) {
-                session.threadId = null;
+                const hasWarmBootstrap = !!session.threadBootstrapFingerprint || !!session.bootstrapPromise;
+                if (!hasWarmBootstrap) {
+                    session.threadId = null;
+                    session.bootstrapPromise = null;
+                    session.bootstrapGeneration++;
+                }
             }
+            let awaitedBootstrap = false;
+            let bootstrapTimedOut = false;
+            if (!internalOpts?.skipBootstrapWait && session.bootstrapPromise) {
+                awaitedBootstrap = true;
+                try {
+                    await session.bootstrapPromise;
+                }
+                catch {
+                    bootstrapTimedOut = true;
+                }
+                session.bootstrapPromise = null;
+            }
+            let coldThreadCreated = false;
             if (!session.threadId) {
                 if (requestedThreadId) {
                     const response = await this.sendRequest(session, 'thread/resume', {
@@ -420,6 +1028,7 @@ class CodexAppServerManager {
                         modelProvider: 'openai',
                     });
                     session.threadId = extractThreadId(response);
+                    coldThreadCreated = true;
                 }
                 else {
                     const response = await this.sendRequest(session, 'thread/start', {
@@ -433,14 +1042,37 @@ class CodexAppServerManager {
                         ephemeral: false,
                     });
                     session.threadId = extractThreadId(response);
+                    coldThreadCreated = true;
+                }
+            }
+            if (!internalOpts?.suppressSendPathLog) {
+                if (bootstrapTimedOut) {
+                    this.logInfo(`[cli-warm] send_path=bootstrap_timeout fallback=cold`);
+                }
+                else if (awaitedBootstrap && session.threadId && !coldThreadCreated) {
+                    this.logInfo(`[cli-warm] send_path=waited_on_warm`);
+                }
+                else if (session.threadId && !awaitedBootstrap && !coldThreadCreated) {
+                    this.logInfo(`[cli-warm] send_path=reused_warm_thread`);
+                }
+                else {
+                    this.logInfo(`[cli-warm] send_path=cold_start`);
                 }
             }
+            if (session.threadId && !coldThreadCreated) {
+                const reuseMode = awaitedBootstrap
+                    ? 'awaited_bootstrap'
+                    : session.threadBootstrapFingerprint
+                        ? 'warm_bootstrap'
+                        : 'existing_thread';
+                this.logInfo(`[codex-app-server] codex_thread_reuse conversationId=${JSON.stringify(opts.conversationId)} botId=${JSON.stringify(opts.botId)} threadId=${JSON.stringify(session.threadId)} mode=${reuseMode} forceFreshSession=${opts.forceFreshSession ? 'true' : 'false'}`);
+            }
             const threadId = session.threadId;
             if (!threadId) {
                 throw new Error('Codex app-server did not return a thread id');
             }
             activeTurn.threadId = threadId;
-            const turnStartResponse = await this.sendRequest(session, 'turn/start', {
+            const turnStartParams = {
                 threadId,
                 cwd: opts.cwd,
                 approvalPolicy: codexSettings.approvalPolicy,
@@ -450,13 +1082,18 @@ class CodexAppServerManager {
                 input: buildCodexAppServerInput(opts.messages),
                 model: opts.model || null,
                 serviceTier: codexSettings.serviceTier,
-                summary: codexSettings.reasoningSummary,
-            });
+            };
+            if (codexSettings.reasoningSummary && codexSettings.reasoningSummary !== 'none') {
+                turnStartParams.summary = codexSettings.reasoningSummary;
+            }
+            const turnStartResponse = await this.sendRequest(session, 'turn/start', turnStartParams);
             activeTurn.turnId = extractTurnId(turnStartResponse);
+            (0, managed_process_registry_1.markTurnActivity)(session.key, 'codex_turn_started');
             return await completionPromise;
         }
         finally {
             opts.abortSignal?.removeEventListener('abort', abortHandler);
+            (0, managed_process_registry_1.markTurnFinished)(session.key, 'codex_turn_finished');
         }
     }
     sendNotification(session, method, params) {
@@ -488,6 +1125,8 @@ class CodexAppServerManager {
         });
     }
     handleStdout(session, chunk) {
+        if (chunk)
+            (0, managed_process_registry_1.markTurnActivity)(session.key, 'codex_stdout');
         session.stdoutCarry += chunk;
         const lines = session.stdoutCarry.split(/\r?\n/);
         session.stdoutCarry = lines.pop() || '';
@@ -570,7 +1209,13 @@ class CodexAppServerManager {
         }
         if (message.method === 'item/agentMessage/delta' && isTurnMatch(session.activeTurn, params) && session.activeTurn) {
             const delta = typeof params.delta === 'string' ? params.delta : '';
+            const itemId = extractItemId(params);
             if (delta) {
+                if (itemId && session.activeTurn.commentaryItemIds.has(itemId)) {
+                    const existing = session.activeTurn.commentaryTextByItemId.get(itemId) || '';
+                    session.activeTurn.commentaryTextByItemId.set(itemId, existing + delta);
+                    return;
+                }
                 session.activeTurn.finalContent += delta;
                 await this.emitChunk(session.activeTurn, delta);
             }
@@ -587,20 +1232,20 @@ class CodexAppServerManager {
         if (message.method === 'item/commandExecution/outputDelta' && isTurnMatch(session.activeTurn, params)) {
             const delta = typeof params.delta === 'string' ? params.delta : '';
             if (delta) {
-                await this.emitDetail(session.activeTurn, delta);
+                await this.emitDetail(session.activeTurn, delta, 'command_output');
             }
             return;
         }
         if (message.method === 'item/fileChange/outputDelta' && isTurnMatch(session.activeTurn, params)) {
             const delta = typeof params.delta === 'string' ? params.delta : '';
             if (delta) {
-                await this.emitDetail(session.activeTurn, delta);
+                await this.emitDetail(session.activeTurn, delta, 'file_output');
             }
             return;
         }
         if (message.method === 'item/mcpToolCall/progress' && isTurnMatch(session.activeTurn, params)) {
             if (typeof params.message === 'string') {
-                await this.emitDetail(session.activeTurn, params.message);
+                await this.emitDetail(session.activeTurn, params.message, 'mcp_progress');
             }
             return;
         }
@@ -611,12 +1256,46 @@ class CodexAppServerManager {
             return;
         }
         if (message.method === 'item/started' && isTurnMatch(session.activeTurn, params)) {
+            const commentaryItemId = extractItemId(params);
+            if (session.activeTurn && commentaryItemId && extractAgentMessagePhase(params) === 'commentary') {
+                session.activeTurn.commentaryItemIds.add(commentaryItemId);
+                session.activeTurn.commentaryTextByItemId.set(commentaryItemId, '');
+                return;
+            }
+            // Emit structured tool call event for tool-like items (command_execution,
+            // file_change, mcpToolCall, applyPatch). Also emit a textual detail line
+            // for the live activity log.
+            const toolEvent = buildToolEventFromItem('call', params);
+            if (toolEvent && session.activeTurn?.onToolEvent) {
+                try {
+                    await session.activeTurn.onToolEvent(toolEvent);
+                }
+                catch { /* swallow */ }
+            }
             const detail = describeItemProgress(message.method, params);
             if (detail)
                 await this.emitDetail(session.activeTurn, detail);
             return;
         }
         if (message.method === 'item/completed' && isTurnMatch(session.activeTurn, params)) {
+            const commentaryItemId = extractItemId(params);
+            if (session.activeTurn && commentaryItemId && session.activeTurn.commentaryItemIds.has(commentaryItemId)) {
+                const completedText = (typeof params?.item?.text === 'string' && params.item.text)
+                    || session.activeTurn.commentaryTextByItemId.get(commentaryItemId)
+                    || '';
+                session.activeTurn.commentaryItemIds.delete(commentaryItemId);
+                session.activeTurn.commentaryTextByItemId.delete(commentaryItemId);
+                await this.emitCommentary(session.activeTurn, completedText);
+                return;
+            }
+            // Emit structured tool result event for tool-like items.
+            const toolEvent = buildToolEventFromItem('result', params);
+            if (toolEvent && session.activeTurn?.onToolEvent) {
+                try {
+                    await session.activeTurn.onToolEvent(toolEvent);
+                }
+                catch { /* swallow */ }
+            }
             const detail = describeItemProgress(message.method, params);
             if (detail)
                 await this.emitDetail(session.activeTurn, detail);
@@ -656,11 +1335,13 @@ class CodexAppServerManager {
         }
     }
     handleStderr(session, chunk) {
+        if (chunk)
+            (0, managed_process_registry_1.markTurnActivity)(session.key, 'codex_stderr');
         appendEvent(session.activeTurn?.eventLog, 'stderr', 'stderr', chunk);
-        void this.emitDetail(session.activeTurn, chunk);
+        void this.emitDetail(session.activeTurn, chunk, 'stderr');
     }
     handleProcessError(session, err) {
-        this.logWarn(`[codex-app-server] Process error for ${session.key}: ${err.message}`);
+        this.logWarn(`[codex-app-server] Process error for ${session.key}: ${err.stack || err.message}`);
         if (session.activeTurn) {
             const activeTurn = session.activeTurn;
             session.activeTurn = null;
@@ -672,8 +1353,10 @@ class CodexAppServerManager {
         session.pendingRequests.clear();
         session.closed = true;
         this.sessions.delete(session.key);
+        (0, managed_process_registry_1.unregisterProcess)(session.key, false);
     }
     handleProcessClose(session, code, signal) {
+        this.logWarn(`[codex-app-server] Process closed for ${session.key}: code=${code ?? 'null'} signal=${signal ?? 'null'} activeTurn=${session.activeTurn ? 'yes' : 'no'} pendingRequests=${session.pendingRequests.size}`);
         if (session.stdoutCarry.trim()) {
             const parsed = safeJsonParse(session.stdoutCarry.trim());
             if (parsed) {
@@ -693,6 +1376,7 @@ class CodexAppServerManager {
         }
         session.closed = true;
         this.sessions.delete(session.key);
+        (0, managed_process_registry_1.unregisterProcess)(session.key, false);
         const closeError = new Error(`Codex app-server exited${code !== null ? ` with code ${code}` : ''}${signal ? ` (${signal})` : ''}`);
         for (const pending of session.pendingRequests.values()) {
             pending.reject(closeError);
@@ -716,6 +1400,20 @@ class CodexAppServerManager {
         });
         await activeTurn.callbackChain;
     }
+    async emitCommentary(activeTurn, text) {
+        if (!activeTurn?.onCommentary)
+            return;
+        const normalized = normalizeDetail(text);
+        if (!normalized || normalized === activeTurn.lastCommentaryText)
+            return;
+        activeTurn.lastCommentaryText = normalized;
+        activeTurn.callbackChain = activeTurn.callbackChain.then(async () => {
+            await activeTurn.onCommentary?.(normalized);
+        }).catch((err) => {
+            this.logWarn(`[codex-app-server] onCommentary callback failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+        await activeTurn.callbackChain;
+    }
     async emitThinkingChunk(activeTurn, chunk) {
         if (!activeTurn?.onThinkingChunk || !chunk)
             return;
@@ -726,10 +1424,10 @@ class CodexAppServerManager {
         });
         await activeTurn.callbackChain;
     }
-    async emitDetail(activeTurn, detail) {
+    async emitDetail(activeTurn, detail, source = 'status') {
         if (!activeTurn?.onDetail)
             return;
-        const normalized = normalizeDetail(detail);
+        const normalized = prepareLiveDetailForUser(activeTurn, detail, source);
         if (!normalized)
             return;
         if (activeTurn.detailFingerprints.has(normalized))
@@ -757,7 +1455,9 @@ exports.__codexAppServerTestUtils = {
     LOCAL_ONLY_ERROR,
     buildCodexAppServerInput,
     buildCodexAppServerToolEnv,
+    buildTurnMcpToolEnv,
     scrubCodexAppServerEnv,
+    computeEnvFingerprint,
     buildApprovalResponse,
     buildTurnUsage,
     createEventLog,