@cereworker/core 26.329.24 → 26.329.26

package/dist/orchestrator.js

@@ -9,11 +9,16 @@ import { estimateMessageTokens, shouldCompact, buildCompactionMessages } from '.
 import { createAbortError, throwIfAborted } from './abort.js';
 import { ToolRuntime, } from './tool-runtime.js';
 const log = createLogger('orchestrator');
+const TASK_COMPLETE_TOOL = 'task_complete';
+const TASK_BLOCKED_TOOL = 'task_blocked';
+const INTERNAL_TASK_SIGNAL_TOOL_NAMES = new Set([TASK_COMPLETE_TOOL, TASK_BLOCKED_TOOL]);
+const COMPLETION_RETRY_PROMPT = '[Cerebellum] Your last turn ended without a final answer. Continue from where you left off and end by calling task_complete or task_blocked before your final answer.';
 export class Orchestrator extends TypedEventEmitter {
     conversations;
     cerebrum = null;
     cerebellum = null;
     subAgentManager = null;
+    internalTools = new Map();
     tools = new Map();
     activeConversationId = null;
     systemContext = null;
@@ -46,8 +51,12 @@ export class Orchestrator extends TypedEventEmitter {
     streamNudgeCount = 0;
     streamStallThreshold = 30_000;
     maxNudgeRetries = 2;
+    maxCompletionRetries = 2;
     streamPhase = 'idle';
     activeToolCall = null;
+    currentStreamTurn = null;
+    currentAttemptCompletionState = null;
+    streamAbortGraceMs = 1_000;
     taskConversations = new Map();
     taskRunning = new Set();
     recurringTasks = [];
@@ -62,13 +71,16 @@ export class Orchestrator extends TypedEventEmitter {
         super();
         this.conversations = options?.conversationStore ?? new ConversationStore();
         this.toolRuntime = new ToolRuntime(options?.toolRuntime);
+        this.registerInternalTools();
         if (options?.compaction) {
             this.compactionConfig = { ...this.compactionConfig, ...options.compaction };
         }
         if (options?.streamStallThreshold)
             this.streamStallThreshold = options.streamStallThreshold * 1000;
-        if (options?.maxNudgeRetries)
+        if (options?.maxNudgeRetries) {
             this.maxNudgeRetries = options.maxNudgeRetries;
+            this.maxCompletionRetries = options.maxNudgeRetries;
+        }
     }
     setCerebrum(cerebrum) {
         this.cerebrum = cerebrum;
@@ -116,12 +128,108 @@ export class Orchestrator extends TypedEventEmitter {
     getConversationStore() {
         return this.conversations;
     }
+    registerInternalTools() {
+        this.internalTools.set(TASK_COMPLETE_TOOL, {
+            description: 'Record that a tool-driven task is complete. Call this once right before your final answer with a concise summary and concrete evidence.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    summary: { type: 'string', description: 'Short summary of what was completed' },
+                    evidence: { type: 'string', description: 'Concrete evidence proving completion' },
+                },
+                required: ['summary', 'evidence'],
+                additionalProperties: false,
+            },
+            execute: async (args) => this.recordCompletionSignal('complete', args),
+        });
+        this.internalTools.set(TASK_BLOCKED_TOOL, {
+            description: 'Record that you are blocked and cannot finish the task. Call this once right before your final answer with the blocker and evidence.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    blocker: { type: 'string', description: 'Specific blocker preventing completion' },
+                    evidence: { type: 'string', description: 'Concrete evidence showing the blocker' },
+                },
+                required: ['blocker', 'evidence'],
+                additionalProperties: false,
+            },
+            execute: async (args) => this.recordCompletionSignal('blocked', args),
+        });
+    }
+    getAllTools() {
+        return new Map([...this.tools, ...this.internalTools]);
+    }
+    isInternalTaskSignalTool(name) {
+        return INTERNAL_TASK_SIGNAL_TOOL_NAMES.has(name.trim() || name);
+    }
+    async recordCompletionSignal(signal, args) {
+        const state = this.currentAttemptCompletionState;
+        if (!state) {
+            return {
+                output: 'No active turn is available for task completion tracking.',
+                isError: true,
+            };
+        }
+        const evidence = String(args.evidence ?? '').trim();
+        if (!evidence) {
+            return {
+                output: 'A non-empty evidence field is required.',
+                isError: true,
+            };
+        }
+        if (signal === 'complete') {
+            const summary = String(args.summary ?? '').trim();
+            if (!summary) {
+                return {
+                    output: 'A non-empty summary field is required.',
+                    isError: true,
+                };
+            }
+            if (state.successfulExternalToolCount === 0) {
+                return {
+                    output: 'task_complete requires at least one successful external tool result in this attempt.',
+                    isError: true,
+                };
+            }
+            state.signal = 'complete';
+            state.summary = summary;
+            state.blocker = undefined;
+            state.evidence = evidence;
+        }
+        else {
+            const blocker = String(args.blocker ?? '').trim();
+            if (!blocker) {
+                return {
+                    output: 'A non-empty blocker field is required.',
+                    isError: true,
+                };
+            }
+            state.signal = 'blocked';
+            state.blocker = blocker;
+            state.summary = undefined;
+            state.evidence = evidence;
+        }
+        this.emitCompletionTrace('signal_recorded', signal === 'complete'
+            ? `Recorded task_complete signal with evidence: ${evidence}`
+            : `Recorded task_blocked signal with evidence: ${evidence}`, signal, 'info');
+        return {
+            output: signal === 'complete' ? 'Task completion recorded.' : 'Task blocker recorded.',
+            isError: false,
+            metadata: {
+                internal: true,
+                signal,
+            },
+        };
+    }
     registerTool(name, tool) {
+        if (this.internalTools.has(name)) {
+            throw new Error(`Tool name ${name} is reserved for internal task signaling`);
+        }
         this.tools.set(name, tool);
     }
     registerTools(tools) {
         for (const [name, tool] of Object.entries(tools)) {
-            this.tools.set(name, tool);
+            this.registerTool(name, tool);
         }
     }
     async executeTool(name, args, options) {
@@ -131,13 +239,16 @@ export class Orchestrator extends TypedEventEmitter {
                 name,
                 args,
             },
-            tools: this.tools,
+            tools: this.getAllTools(),
             conversationId: options?.conversationId,
             sessionKey: options?.sessionKey,
             scopeKey: options?.scopeKey,
         });
     }
     unregisterTool(name) {
+        if (this.internalTools.has(name)) {
+            return false;
+        }
         return this.tools.delete(name);
     }
     setProfile(profile) {
@@ -454,18 +565,35 @@ export class Orchestrator extends TypedEventEmitter {
         };
     }
     markStreamWaitingModel(activityAt = Date.now()) {
+        const phaseChanged = this.streamPhase !== 'waiting_model' || this.activeToolCall !== null;
         this.lastStreamActivityAt = activityAt;
         this.streamPhase = 'waiting_model';
         this.activeToolCall = null;
+        if (phaseChanged) {
+            this.logStreamDebug('stream_phase_changed', {
+                phase: this.streamPhase,
+            });
+        }
     }
     markStreamWaitingTool(toolCall, activityAt = Date.now()) {
+        const normalizedToolName = toolCall.name.trim() || toolCall.name;
+        const phaseChanged = this.streamPhase !== 'waiting_tool'
+            || this.activeToolCall?.id !== toolCall.id
+            || this.activeToolCall?.name !== normalizedToolName;
         this.lastStreamActivityAt = activityAt;
         this.streamPhase = 'waiting_tool';
         this.activeToolCall = {
             id: toolCall.id,
-            name: toolCall.name.trim() || toolCall.name,
+            name: normalizedToolName,
             startedAt: activityAt,
         };
+        if (phaseChanged) {
+            this.logStreamDebug('stream_phase_changed', {
+                phase: this.streamPhase,
+                activeToolName: normalizedToolName,
+                activeToolCallId: toolCall.id,
+            });
+        }
     }
     resetStreamState() {
         this.streamPhase = 'idle';
@@ -480,6 +608,162 @@ export class Orchestrator extends TypedEventEmitter {
             activeToolStartedAt: this.activeToolCall?.startedAt,
         };
     }
+    describeStreamLocation() {
+        if (this.streamPhase === 'waiting_tool') {
+            return this.activeToolCall?.name
+                ? `waiting_tool/${this.activeToolCall.name}`
+                : 'waiting_tool';
+        }
+        return this.streamPhase;
+    }
+    logStreamDebug(msg, data) {
+        if (!this.currentStreamTurn)
+            return;
+        log.debug(msg, {
+            turnId: this.currentStreamTurn.turnId,
+            attempt: this.currentStreamTurn.attempt,
+            conversationId: this.currentStreamTurn.conversationId,
+            ...data,
+        });
+    }
+    emitWatchdog(stage, message, options) {
+        if (!this.currentStreamTurn)
+            return;
+        const payload = {
+            stage,
+            turnId: this.currentStreamTurn.turnId,
+            attempt: this.currentStreamTurn.attempt,
+            conversationId: this.currentStreamTurn.conversationId,
+            message,
+            ...this.getStreamDiagnostics(options?.elapsedSeconds),
+        };
+        const level = options?.level ?? 'info';
+        switch (level) {
+            case 'debug':
+                log.debug(`watchdog_${stage}`, payload);
+                break;
+            case 'warn':
+                log.warn(`watchdog_${stage}`, payload);
+                break;
+            case 'error':
+                log.error(`watchdog_${stage}`, payload);
+                break;
+            default:
+                log.info(`watchdog_${stage}`, payload);
+                break;
+        }
+        this.emit({ type: 'cerebrum:watchdog', ...payload });
+    }
+    emitCompletionTrace(stage, message, signal, level = 'info') {
+        if (!this.currentStreamTurn)
+            return;
+        const payload = {
+            stage,
+            turnId: this.currentStreamTurn.turnId,
+            attempt: this.currentStreamTurn.attempt,
+            conversationId: this.currentStreamTurn.conversationId,
+            signal,
+            message,
+            ...this.getStreamDiagnostics(),
+        };
+        switch (level) {
+            case 'debug':
+                log.debug(`completion_${stage}`, payload);
+                break;
+            case 'warn':
+                log.warn(`completion_${stage}`, payload);
+                break;
+            case 'error':
+                log.error(`completion_${stage}`, payload);
+                break;
+            default:
+                log.info(`completion_${stage}`, payload);
+                break;
+        }
+        this.emit({ type: 'cerebrum:completion', ...payload });
+    }
+    createAttemptCompletionState() {
+        return {
+            signal: 'none',
+            evidence: '',
+            successfulExternalToolCount: 0,
+            externalToolCallCount: 0,
+            internalToolCallCount: 0,
+        };
+    }
+    evaluateCompletionGuard(displayContent, finishMeta, completionState) {
+        const trimmedContent = displayContent.trim();
+        const hadExternalToolActivity = completionState.externalToolCallCount > 0;
+        const endedOnToolCalls = finishMeta?.finishReason === 'tool-calls'
+            || finishMeta?.stepFinishReasons.at(-1) === 'tool-calls';
+        if (trimmedContent.length === 0 && hadExternalToolActivity) {
+            return {
+                message: 'Turn ended after tool activity without a final answer.',
+                signal: completionState.signal,
+            };
+        }
+        if (endedOnToolCalls) {
+            return {
+                message: 'Turn ended on tool-calls without a final answer.',
+                signal: completionState.signal,
+            };
+        }
+        if (hadExternalToolActivity && completionState.signal === 'none') {
+            return {
+                message: 'Tool-driven turn ended without task_complete or task_blocked.',
+                signal: completionState.signal,
+            };
+        }
+        return null;
+    }
+    async awaitStreamAttempt(streamPromise, abortController) {
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let abortTimer = null;
+            const cleanup = () => {
+                abortController.signal.removeEventListener('abort', onAbort);
+                if (abortTimer) {
+                    clearTimeout(abortTimer);
+                    abortTimer = null;
+                }
+            };
+            const settleResolve = () => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve();
+            };
+            const settleReject = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            const onAbort = () => {
+                this.logStreamDebug('provider_abort_observed', {
+                    phase: this.streamPhase,
+                    activeToolName: this.activeToolCall?.name,
+                    activeToolCallId: this.activeToolCall?.id,
+                });
+                if (abortTimer)
+                    return;
+                abortTimer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    const elapsedSeconds = Math.max(1, Math.round((Date.now() - this.lastStreamActivityAt) / 1000));
+                    this.emitWatchdog('teardown_timeout', `Provider did not settle within ${this.streamAbortGraceMs}ms after abort; continuing retry.`, { level: 'warn', elapsedSeconds });
+                    settleReject(createAbortError('Stream aborted'));
+                }, this.streamAbortGraceMs);
+            };
+            abortController.signal.addEventListener('abort', onAbort, { once: true });
+            if (abortController.signal.aborted) {
+                onAbort();
+            }
+            streamPromise.then(settleResolve, settleReject);
+        });
+    }
     startStreamWatchdog() {
         this.stopStreamWatchdog();
         this.markStreamWaitingModel();
@@ -493,19 +777,20 @@ export class Orchestrator extends TypedEventEmitter {
                 return;
             const elapsedSeconds = Math.round(elapsed / 1000);
             const diagnostics = this.getStreamDiagnostics(elapsedSeconds);
-            log.warn('Cerebrum stream stalled', diagnostics);
+            this.emitWatchdog('stalled', `Stalled after ${elapsedSeconds}s while ${this.describeStreamLocation()}.`, { level: 'warn', elapsedSeconds });
             this.emit({ type: 'cerebrum:stall', ...diagnostics });
             if (!this.cerebellum?.isConnected()) {
                 // Cerebellum dropped mid-stream — abort the current turn
-                log.warn('Cerebellum disconnected during active stream — aborting');
+                this.emitWatchdog('abort_issued', 'Cerebellum disconnected during an active stream; aborting the turn.', { level: 'warn', elapsedSeconds });
                 this.abortController?.abort();
                 return;
             }
             this._nudgeInFlight = true;
             const doNudge = () => {
                 this.streamNudgeCount++;
-                log.info('Cerebellum nudging stalled stream', { attempt: this.streamNudgeCount, ...diagnostics });
+                this.emitWatchdog('nudge_requested', `Cerebellum requested nudge ${this.streamNudgeCount}/${this.maxNudgeRetries} after ${elapsedSeconds}s while ${this.describeStreamLocation()}.`, { level: 'info', elapsedSeconds });
                 this.emit({ type: 'cerebrum:stall:nudge', attempt: this.streamNudgeCount, ...diagnostics });
+                this.emitWatchdog('abort_issued', `Aborting stalled stream attempt ${this.currentStreamTurn?.attempt ?? 0}.`, { level: 'warn', elapsedSeconds });
                 this.abortController?.abort();
             };
             void (async () => {
@@ -549,225 +834,365 @@ export class Orchestrator extends TypedEventEmitter {
             this.emit({ type: 'message:user', message: userMessage });
         }
         this.streamNudgeCount = 0;
-        // Retry loop — nudge aborts land here for retry
-        for (let attempt = 0; attempt <= this.maxNudgeRetries; attempt++) {
-            const abortController = new AbortController();
-            const isCurrentAttempt = () => this.abortController === abortController;
-            this.abortController = abortController;
-            if (attempt > 0) {
-                log.info('Retrying Cerebrum stream after watchdog nudge', {
-                    attempt,
+        let completionRetryCount = 0;
+        const turnId = nanoid(10);
+        const maxTotalAttempts = 1 + this.maxNudgeRetries + this.maxCompletionRetries;
+        let loopTerminated = false;
+        let nextRetryCause = null;
+        try {
+            for (let attempt = 0; attempt < maxTotalAttempts; attempt++) {
+                const abortController = new AbortController();
+                const attemptNumber = attempt + 1;
+                const retryCause = nextRetryCause;
+                nextRetryCause = null;
+                const completionState = this.createAttemptCompletionState();
+                let completionGuardFailure = null;
+                const stallRetryCountAtStart = this.streamNudgeCount;
+                const isCurrentAttempt = () => this.abortController === abortController;
+                this.abortController = abortController;
+                this.currentAttemptCompletionState = completionState;
+                this.currentStreamTurn = {
+                    turnId,
+                    attempt: attemptNumber,
+                    conversationId: convId,
+                };
+                log.info('stream_started', {
+                    turnId,
+                    attempt: attemptNumber,
                     conversationId: convId,
+                    stallRetryCount: this.streamNudgeCount,
+                    completionRetryCount,
+                    retryCause,
                 });
-            }
-            this.emit({ type: 'message:cerebrum:start', conversationId: convId });
-            this.startStreamWatchdog();
-            let messages = this.conversations.getMessages(convId);
-            // Context window compaction
-            if (this.compactionConfig.enabled &&
-                this.cerebrum?.summarize &&
-                shouldCompact(messages, this.compactionConfig.contextWindow, this.compactionConfig.threshold)) {
-                try {
-                    const keepRecent = this.compactionConfig.keepRecentMessages;
-                    const olderMessages = messages.slice(0, Math.max(0, messages.length - keepRecent));
-                    if (olderMessages.length > 0) {
-                        log.info('Compacting conversation', {
-                            totalMessages: messages.length,
-                            compactingMessages: olderMessages.length,
-                            estimatedTokens: estimateMessageTokens(messages),
+                this.emit({ type: 'message:cerebrum:start', conversationId: convId });
+                this.startStreamWatchdog();
+                let messages = this.conversations.getMessages(convId);
+                // Context window compaction
+                if (this.compactionConfig.enabled &&
+                    this.cerebrum?.summarize &&
+                    shouldCompact(messages, this.compactionConfig.contextWindow, this.compactionConfig.threshold)) {
+                    try {
+                        const keepRecent = this.compactionConfig.keepRecentMessages;
+                        const olderMessages = messages.slice(0, Math.max(0, messages.length - keepRecent));
+                        if (olderMessages.length > 0) {
+                            log.info('Compacting conversation', {
+                                totalMessages: messages.length,
+                                compactingMessages: olderMessages.length,
+                                estimatedTokens: estimateMessageTokens(messages),
+                            });
+                            const summary = await this.cerebrum.summarize(olderMessages);
+                            messages = buildCompactionMessages(messages, summary, keepRecent);
+                        }
+                    }
+                    catch (error) {
+                        log.warn('Compaction failed, continuing with full context', {
+                            error: error instanceof Error ? error.message : String(error),
                         });
-                        const summary = await this.cerebrum.summarize(olderMessages);
-                        messages = buildCompactionMessages(messages, summary, keepRecent);
                     }
                 }
-                catch (error) {
-                    log.warn('Compaction failed, continuing with full context', {
-                        error: error instanceof Error ? error.message : String(error),
-                    });
-                }
-            }
-            // Build system prompt with runtime state + skills context
-            const instance = this.instanceStore?.get();
-            const basePrompt = buildSystemPrompt({
-                cerebellumConnected: this.cerebellum?.isConnected() ?? false,
-                tools: this.tools,
-                autoMode: this.autoMode,
-                gatewayMode: this.gatewayMode,
-                connectedNodes: this.connectedNodes,
-                gatewayUrl: this.gatewayUrl,
-                profile: this.profile,
-                finetuneStatus: {
-                    enabled: !!this.fineTuneDataProvider,
-                    status: this.fineTuneStatus.status,
-                    progress: this.fineTuneStatus.progress,
-                    lastJobId: this.fineTuneStatus.jobId || undefined,
-                },
-                recurringTasks: this.recurringTasks,
-                instanceId: instance?.id,
-                instanceCreatedAt: instance?.createdAt,
-                finetuneCount: instance?.finetuneLineage.length,
-                proactiveEnabled: this.proactiveEnabled,
-                discoveryMode: this.discoveryMode,
-            });
-            const systemParts = [basePrompt];
-            if (this.systemContext)
-                systemParts.push(this.systemContext);
-            const fullSystemPrompt = systemParts.join('\n\n---\n\n');
-            const allMessages = [
-                { id: 'system', role: 'system', content: fullSystemPrompt, timestamp: 0 },
-                ...messages,
-            ];
-            const toolDefs = Object.fromEntries(this.tools);
-            let fullContent = '';
-            const throwIfToolAttemptAborted = () => {
-                if (!isCurrentAttempt()) {
-                    throw createAbortError('Tool execution aborted');
-                }
-                throwIfAborted(abortController.signal, 'Tool execution aborted');
-            };
-            try {
-                await this.cerebrum.stream(allMessages, toolDefs, {
-                    onChunk: (chunk) => {
-                        if (!isCurrentAttempt() || abortController.signal.aborted)
-                            return;
-                        fullContent += chunk;
-                        this.markStreamWaitingModel();
-                        this.emit({ type: 'message:cerebrum:chunk', chunk });
+                // Build system prompt with runtime state + skills context
+                const instance = this.instanceStore?.get();
+                const allTools = this.getAllTools();
+                const basePrompt = buildSystemPrompt({
+                    cerebellumConnected: this.cerebellum?.isConnected() ?? false,
+                    tools: allTools,
+                    autoMode: this.autoMode,
+                    gatewayMode: this.gatewayMode,
+                    connectedNodes: this.connectedNodes,
+                    gatewayUrl: this.gatewayUrl,
+                    profile: this.profile,
+                    finetuneStatus: {
+                        enabled: !!this.fineTuneDataProvider,
+                        status: this.fineTuneStatus.status,
+                        progress: this.fineTuneStatus.progress,
+                        lastJobId: this.fineTuneStatus.jobId || undefined,
                     },
-                    onToolCall: async (toolCall) => {
-                        throwIfToolAttemptAborted();
-                        this.markStreamWaitingTool(toolCall);
-                        const requestedToolName = toolCall.name;
-                        const normalizedToolName = requestedToolName.trim() || requestedToolName;
-                        this.emit({ type: 'message:cerebrum:toolcall', toolCall: { ...toolCall, name: normalizedToolName } });
-                        this.emit({ type: 'tool:start', callId: toolCall.id, name: normalizedToolName });
-                        const { toolName, result } = await this.toolRuntime.execute({
-                            toolCall,
-                            tools: this.tools,
-                            conversationId: convId,
-                            sessionKey: 'agent:main',
-                            scopeKey: convId,
-                            abortSignal: abortController.signal,
-                        });
-                        throwIfAborted(abortController.signal, 'Tool execution aborted');
-                        this.markStreamWaitingModel();
-                        this.emit({ type: 'tool:end', result });
-                        // Cerebellum verification (non-blocking)
-                        if (this.cerebellum?.isConnected() && this.verificationEnabled) {
-                            try {
-                                throwIfAborted(abortController.signal, 'Tool execution aborted');
-                                this.emit({ type: 'verification:start', callId: toolCall.id, toolName });
-                                const toolArgs = {};
-                                for (const [k, v] of Object.entries(toolCall.args)) {
-                                    toolArgs[k] = String(v);
+                    recurringTasks: this.recurringTasks,
+                    instanceId: instance?.id,
+                    instanceCreatedAt: instance?.createdAt,
+                    finetuneCount: instance?.finetuneLineage.length,
+                    proactiveEnabled: this.proactiveEnabled,
+                    discoveryMode: this.discoveryMode,
+                });
+                const systemParts = [basePrompt];
+                if (this.systemContext)
+                    systemParts.push(this.systemContext);
+                const fullSystemPrompt = systemParts.join('\n\n---\n\n');
+                const allMessages = [
+                    { id: 'system', role: 'system', content: fullSystemPrompt, timestamp: 0 },
+                    ...messages,
+                ];
+                const toolDefs = Object.fromEntries(allTools);
+                let fullContent = '';
+                const throwIfToolAttemptAborted = () => {
+                    if (!isCurrentAttempt()) {
+                        throw createAbortError('Tool execution aborted');
+                    }
+                    throwIfAborted(abortController.signal, 'Tool execution aborted');
+                };
+                try {
+                    const streamPromise = this.cerebrum.stream(allMessages, toolDefs, {
+                        onChunk: (chunk) => {
+                            if (!isCurrentAttempt() || abortController.signal.aborted)
+                                return;
+                            fullContent += chunk;
+                            this.markStreamWaitingModel();
+                            this.emit({ type: 'message:cerebrum:chunk', chunk });
+                        },
+                        onToolCall: async (toolCall) => {
+                            throwIfToolAttemptAborted();
+                            this.logStreamDebug('tool_callback_started', {
+                                toolName: toolCall.name.trim() || toolCall.name,
+                                toolCallId: toolCall.id,
+                            });
+                            this.markStreamWaitingTool(toolCall);
+                            const requestedToolName = toolCall.name;
+                            const normalizedToolName = requestedToolName.trim() || requestedToolName;
+                            const isInternalTaskSignal = this.isInternalTaskSignalTool(normalizedToolName);
+                            if (isInternalTaskSignal) {
+                                completionState.internalToolCallCount++;
+                            }
+                            else {
+                                completionState.externalToolCallCount++;
+                                this.emit({ type: 'message:cerebrum:toolcall', toolCall: { ...toolCall, name: normalizedToolName } });
+                                this.emit({ type: 'tool:start', callId: toolCall.id, name: normalizedToolName });
+                            }
+                            const { toolName, result } = await this.toolRuntime.execute({
+                                toolCall,
+                                tools: allTools,
+                                conversationId: convId,
+                                sessionKey: 'agent:main',
+                                scopeKey: convId,
+                                abortSignal: abortController.signal,
+                            });
+                            this.logStreamDebug('tool_callback_finished', {
+                                toolName,
+                                toolCallId: toolCall.id,
+                                isError: result.isError,
+                            });
+                            throwIfAborted(abortController.signal, 'Tool execution aborted');
+                            this.markStreamWaitingModel();
+                            if (!isInternalTaskSignal) {
+                                this.emit({ type: 'tool:end', result });
+                            }
+                            if (!isInternalTaskSignal && !result.isError) {
+                                completionState.successfulExternalToolCount++;
+                            }
+                            // Cerebellum verification (non-blocking)
+                            if (!isInternalTaskSignal && this.cerebellum?.isConnected() && this.verificationEnabled) {
+                                try {
+                                    throwIfAborted(abortController.signal, 'Tool execution aborted');
+                                    this.emit({ type: 'verification:start', callId: toolCall.id, toolName });
+                                    const toolArgs = {};
+                                    for (const [k, v] of Object.entries(toolCall.args)) {
+                                        toolArgs[k] = String(v);
+                                    }
+                                    const verifyPromise = this.cerebellum.verifyToolResult(toolName, toolArgs, result.output, !result.isError);
+                                    const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(null), this.verificationTimeoutMs));
+                                    const verification = await Promise.race([verifyPromise, timeoutPromise]);
+                                    throwIfAborted(abortController.signal, 'Tool execution aborted');
+                                    if (verification && !verification.passed) {
+                                        const failedChecks = verification.checks
+                                            .filter((c) => !c.passed)
+                                            .map((c) => c.description)
+                                            .join(', ');
+                                        result.output += `\n[Cerebellum warning: ${failedChecks}]`;
+                                    }
+                                    if (verification) {
+                                        const vResult = {
+                                            passed: verification.passed,
+                                            checks: verification.checks,
+                                            modelVerdict: verification.modelVerdict,
+                                            toolCallId: toolCall.id,
+                                            toolName,
+                                        };
+                                        this.emit({ type: 'verification:end', result: vResult });
+                                    }
                                 }
-                                const verifyPromise = this.cerebellum.verifyToolResult(toolName, toolArgs, result.output, !result.isError);
-                                const timeoutPromise = new Promise((resolve) => setTimeout(() => resolve(null), this.verificationTimeoutMs));
-                                const verification = await Promise.race([verifyPromise, timeoutPromise]);
-                                throwIfAborted(abortController.signal, 'Tool execution aborted');
-                                if (verification && !verification.passed) {
-                                    const failedChecks = verification.checks
-                                        .filter((c) => !c.passed)
-                                        .map((c) => c.description)
-                                        .join(', ');
-                                    result.output += `\n[Cerebellum warning: ${failedChecks}]`;
+                                catch {
+                                    // Verification failure should never block tool execution
                                 }
-                                if (verification) {
-                                    const vResult = {
-                                        passed: verification.passed,
-                                        checks: verification.checks,
-                                        modelVerdict: verification.modelVerdict,
-                                        toolCallId: toolCall.id,
+                            }
+                            throwIfToolAttemptAborted();
+                            if (!isInternalTaskSignal) {
+                                this.conversations.appendMessage(convId, 'tool', result.output, {
+                                    toolResult: result,
+                                    metadata: {
                                         toolName,
-                                    };
-                                    this.emit({ type: 'verification:end', result: vResult });
-                                }
+                                        ...(requestedToolName !== toolName ? { requestedToolName } : {}),
+                                    },
+                                });
                             }
-                            catch {
-                                // Verification failure should never block tool execution
+                            return result;
+                        },
+                        onFinish: (content, toolCalls, finishMeta) => {
+                            if (!isCurrentAttempt() || abortController.signal.aborted)
+                                return;
+                            this.stopStreamWatchdog();
+                            let displayContent = content;
+                            const visibleToolCalls = toolCalls?.filter((toolCall) => !this.isInternalTaskSignalTool(toolCall.name));
+                            log.info('stream_finish_observed', {
+                                turnId,
+                                attempt: attemptNumber,
+                                conversationId: convId,
+                                finishReason: finishMeta?.finishReason,
+                                rawFinishReason: finishMeta?.rawFinishReason,
+                                stepCount: finishMeta?.stepCount ?? 0,
+                                chunkCount: finishMeta?.chunkCount ?? 0,
+                                toolCallCount: finishMeta?.toolCallCount ?? 0,
+                                textChars: finishMeta?.textChars ?? content.length,
+                                completionSignal: completionState.signal,
+                            });
+                            // Check for discovery completion — parse and strip the tag before storing
+                            if (this.discoveryMode && content.includes('<discovery_complete>')) {
+                                const parsed = this.parseDiscoveryCompletion(content);
+                                // Strip the tag block from the displayed/stored content
+                                displayContent = content
+                                    .replace(/<discovery_complete>[\s\S]*?<\/discovery_complete>/g, '')
+                                    .trim();
+                                if (parsed && this.onDiscoveryComplete) {
+                                    this.discoveryMode = false;
+                                    this.onDiscoveryComplete(parsed);
+                                    log.info('Discovery completed', { name: parsed.name });
+                                }
                             }
-                        }
-                        throwIfToolAttemptAborted();
-                        this.conversations.appendMessage(convId, 'tool', result.output, {
-                            toolResult: result,
-                            metadata: {
-                                toolName,
-                                ...(requestedToolName !== toolName ? { requestedToolName } : {}),
-                            },
-                        });
-                        return result;
-                    },
-                    onFinish: (content, toolCalls) => {
-                        if (!isCurrentAttempt() || abortController.signal.aborted)
-                            return;
-                        this.stopStreamWatchdog();
-                        let displayContent = content;
-                        // Check for discovery completion — parse and strip the tag before storing
-                        if (this.discoveryMode && content.includes('<discovery_complete>')) {
-                            const parsed = this.parseDiscoveryCompletion(content);
-                            // Strip the tag block from the displayed/stored content
-                            displayContent = content
-                                .replace(/<discovery_complete>[\s\S]*?<\/discovery_complete>/g, '')
-                                .trim();
-                            if (parsed && this.onDiscoveryComplete) {
-                                this.discoveryMode = false;
-                                this.onDiscoveryComplete(parsed);
-                                log.info('Discovery completed', { name: parsed.name });
+                            const guardFailure = this.evaluateCompletionGuard(displayContent, finishMeta, completionState);
+                            if (guardFailure) {
+                                completionGuardFailure = guardFailure;
+                                this.emitCompletionTrace('guard_triggered', guardFailure.message, guardFailure.signal, 'warn');
+                                log.warn('completion_guard_triggered', {
+                                    turnId,
+                                    attempt: attemptNumber,
+                                    conversationId: convId,
+                                    finishReason: finishMeta?.finishReason,
+                                    rawFinishReason: finishMeta?.rawFinishReason,
+                                    stepCount: finishMeta?.stepCount ?? 0,
+                                    chunkCount: finishMeta?.chunkCount ?? 0,
+                                    toolCallCount: finishMeta?.toolCallCount ?? 0,
+                                    textChars: finishMeta?.textChars ?? displayContent.length,
+                                    completionSignal: completionState.signal,
+                                });
+                                return;
                             }
-                        }
-                        const cerebrumMessage = this.conversations.appendMessage(convId, 'cerebrum', displayContent, toolCalls?.length ? { toolCalls } : undefined);
-                        this.emit({ type: 'message:cerebrum:end', message: cerebrumMessage });
-                        if (attempt > 0) {
-                            log.info('Cerebrum stream recovered after watchdog retry', {
-                                attempt,
+                            const cerebrumMessage = this.conversations.appendMessage(convId, 'cerebrum', displayContent, visibleToolCalls?.length ? { toolCalls: visibleToolCalls } : undefined);
+                            this.emit({ type: 'message:cerebrum:end', message: cerebrumMessage });
+                            log.info('stream_finished', {
+                                turnId,
+                                attempt: attemptNumber,
                                 conversationId: convId,
+                                stallRetryCount: this.streamNudgeCount,
+                                completionRetryCount,
+                                retryCause,
                             });
+                            if (retryCause === 'completion') {
+                                this.emitCompletionTrace('retry_recovered', `Completion retry ${completionRetryCount}/${this.maxCompletionRetries} recovered on attempt ${attemptNumber}.`, completionState.signal, 'info');
+                            }
+                            else if (retryCause === 'stall') {
+                                this.emitWatchdog('retry_recovered', `Stall retry ${this.streamNudgeCount}/${this.maxNudgeRetries} recovered on attempt ${attemptNumber}.`, { level: 'info' });
+                            }
+                        },
+                        onError: (error) => {
+                            if (!isCurrentAttempt())
+                                return;
+                            this.stopStreamWatchdog();
+                            // Don't log/emit if the abort was intentional (nudge or Cerebellum disconnect) — catch block handles it
+                            if (abortController.signal.aborted)
+                                return;
+                            log.error('Cerebrum stream error', { error: error.message });
+                            this.emit({ type: 'error', error });
+                        },
+                    }, { abortSignal: abortController.signal });
+                    await this.awaitStreamAttempt(streamPromise, abortController);
+                    const completionFailure = completionGuardFailure;
+                    if (completionFailure !== null) {
+                        const completionSignal = completionFailure.signal;
+                        if (completionRetryCount < this.maxCompletionRetries) {
+                            completionRetryCount++;
+                            const systemMessage = this.conversations.appendMessage(convId, 'system', COMPLETION_RETRY_PROMPT);
+                            this.emit({ type: 'message:system', message: systemMessage });
+                            this.emitCompletionTrace('retry_started', `Retrying attempt ${attemptNumber + 1} after incomplete completion (${completionRetryCount}/${this.maxCompletionRetries}).`, completionSignal, 'info');
+                            nextRetryCause = 'completion';
+                            continue;
                         }
-                    },
-                    onError: (error) => {
-                        if (!isCurrentAttempt())
-                            return;
-                        this.stopStreamWatchdog();
-                        // Don't log/emit if the abort was intentional (nudge or Cerebellum disconnect) — catch block handles it
-                        if (abortController.signal.aborted)
-                            return;
-                        log.error('Cerebrum stream error', { error: error.message });
-                        this.emit({ type: 'error', error });
-                    },
-                }, { abortSignal: abortController.signal });
-            }
-            catch (error) {
-                const failureState = this.getStreamState();
-                this.stopStreamWatchdog();
-                // Check if this was a nudge-abort (not emergency stop, not a real error)
-                const isNudgeAbort = abortController.signal.aborted && this.streamNudgeCount > 0 && this.streamNudgeCount <= this.maxNudgeRetries;
-                if (isNudgeAbort) {
-                    // Inject nudge message and retry via the for-loop
-                    const systemMessage = this.conversations.appendMessage(convId, 'system', '[Cerebellum] You stopped mid-response. Continue from where you left off.');
-                    this.emit({ type: 'message:system', message: systemMessage });
-                    continue; // retry loop
+                        const diagnosticMessage = this.conversations.appendMessage(convId, 'system', '[Cerebellum] The turn ended repeatedly without a valid completion signal or final answer.');
+                        this.emit({ type: 'message:system', message: diagnosticMessage });
+                        this.emitCompletionTrace('retry_failed', `Completion retries exhausted after ${completionRetryCount}/${this.maxCompletionRetries}: ${completionFailure.message}`, completionSignal, 'error');
+                        this.emit({
+                            type: 'error',
+                            error: new Error('Turn ended without a valid completion signal or final answer.'),
+                        });
+                        loopTerminated = true;
+                        break;
+                    }
+                    loopTerminated = true;
+                    break; // success — exit retry loop
                 }
-                // Check if Cerebellum dropped mid-stream
-                if (this.cerebellum && !this.cerebellum.isConnected() && abortController.signal.aborted) {
-                    const err = new Error('Cerebellum disconnected during active response. Restart it with: docker compose up -d cerebellum');
-                    log.error('Cerebellum disconnected mid-stream', { error: err.message });
+                catch (error) {
+                    const failureState = this.getStreamState();
+                    this.stopStreamWatchdog();
+                    // Check if this was a nudge-abort (not emergency stop, not a real error)
+                    const isNudgeAbort = abortController.signal.aborted
+                        && this.streamNudgeCount > stallRetryCountAtStart
+                        && this.streamNudgeCount <= this.maxNudgeRetries;
+                    if (isNudgeAbort) {
+                        // Inject nudge message and retry via the loop
+                        const systemMessage = this.conversations.appendMessage(convId, 'system', '[Cerebellum] You stopped mid-response. Continue from where you left off.');
+                        this.emit({ type: 'message:system', message: systemMessage });
+                        this.emitWatchdog('retry_started', `Retrying stalled turn with attempt ${attemptNumber + 1} (stall retry ${this.streamNudgeCount}/${this.maxNudgeRetries}).`, { level: 'info' });
+                        nextRetryCause = 'stall';
+                        continue; // retry loop
+                    }
+                    // Check if Cerebellum dropped mid-stream
+                    if (this.cerebellum && !this.cerebellum.isConnected() && abortController.signal.aborted) {
+                        const err = new Error('Cerebellum disconnected during active response. Restart it with: docker compose up -d cerebellum');
+                        log.error('Cerebellum disconnected mid-stream', { error: err.message });
+                        this.emit({ type: 'error', error: err });
+                        loopTerminated = true;
+                        break;
+                    }
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    if (retryCause === 'completion') {
+                        this.emitCompletionTrace('retry_failed', `Completion retry attempt ${attemptNumber} failed: ${err.message}`, completionState.signal, 'error');
+                    }
+                    else if (retryCause === 'stall') {
+                        this.emitWatchdog('retry_failed', `Stall retry attempt ${attemptNumber} failed: ${err.message}`, { level: 'error' });
+                    }
+                    log.error('Send message failed', {
+                        error: err.message,
+                        turnId,
+                        attempt: attemptNumber,
+                        conversationId: convId,
+                        phase: failureState.phase,
+                        activeToolName: failureState.activeToolName,
+                        activeToolCallId: failureState.activeToolCallId,
+                        activeToolStartedAt: failureState.activeToolStartedAt,
+                        stallRetryCount: this.streamNudgeCount,
+                        completionRetryCount,
+                        retryCause,
+                    });
                     this.emit({ type: 'error', error: err });
+                    loopTerminated = true;
                     break;
                 }
-                const err = error instanceof Error ? error : new Error(String(error));
+                finally {
+                    this.currentAttemptCompletionState = null;
+                }
+            }
+            if (!loopTerminated) {
+                const err = new Error(`Retry safety limit reached after ${maxTotalAttempts} attempts.`);
                 log.error('Send message failed', {
                     error: err.message,
-                    attempt,
+                    turnId,
                     conversationId: convId,
-                    phase: failureState.phase,
-                    activeToolName: failureState.activeToolName,
-                    activeToolCallId: failureState.activeToolCallId,
-                    activeToolStartedAt: failureState.activeToolStartedAt,
+                    stallRetryCount: this.streamNudgeCount,
+                    completionRetryCount,
                 });
                 this.emit({ type: 'error', error: err });
             }
-            break; // success — exit retry loop
-        } // end retry for-loop
+        }
+        finally {
+            this.currentStreamTurn = null;
+        }
     }
     async start() {
         if (!this.activeConversationId) {