attocode 0.2.5 → 0.2.6

package/dist/src/core/execution-loop.js

@@ -8,7 +8,7 @@
  * resilience handling, tool execution, and compaction.
  */
 import { isFeatureEnabled } from '../defaults.js';
-import { estimateTokenCount } from '../integrations/utilities/token-estimate.js';
+import { estimateTokenCount, estimateTokensFromCharCount } from '../integrations/utilities/token-estimate.js';
 import { callLLM } from './response-handler.js';
 import { executeToolCalls } from './tool-executor.js';
 import { TIMEOUT_WRAPUP_PROMPT, stableStringify, } from '../integrations/index.js';
@@ -21,11 +21,30 @@ import { invalidateAST } from '../integrations/context/codebase-ast.js';
 import * as fs from 'node:fs';
 const log = createComponentLogger('ExecutionLoop');
 // =============================================================================
+// EXECUTION LOOP DEFAULTS
+// =============================================================================
+export const EXECUTION_LOOP_DEFAULTS = {
+    /** Preview length when compacting long tool outputs */
+    COMPACT_PREVIEW_LENGTH: 200,
+    /** Max expensive results preserved from compaction */
+    MAX_PRESERVED_EXPENSIVE_RESULTS: 6,
+    /** Messages to keep during emergency truncation */
+    PRESERVE_RECENT: 10,
+    /** Max chars per tool output before truncation */
+    MAX_TOOL_OUTPUT_CHARS: 8000,
+    /** Number of TS edits before triggering a type check */
+    TYPE_CHECK_EDIT_THRESHOLD: 5,
+    /** Safety margin ratio for context overflow guard */
+    CONTEXT_SAFETY_RATIO: 0.9,
+    /** Per-result budget safety margin */
+    PER_RESULT_BUDGET_RATIO: 0.95,
+};
+// =============================================================================
 // HELPER FUNCTIONS (extracted from ProductionAgent private methods)
 // =============================================================================
 /**
  * Estimate total tokens in a message array.
- * Uses ~4 chars per token heuristic for fast estimation.
+ * Delegates to the shared token estimation utility (~3.5 chars/token).
  */
 export function estimateContextTokens(messages) {
     let totalChars = 0;
@@ -40,14 +59,13 @@ export function estimateContextTokens(messages) {
             }
         }
     }
-    return Math.ceil(totalChars / 4);
+    return estimateTokensFromCharCount(totalChars);
 }
 /**
  * Compact tool outputs to save context.
  */
 export function compactToolOutputs(messages) {
-    const COMPACT_PREVIEW_LENGTH = 200;
-    const MAX_PRESERVED_EXPENSIVE_RESULTS = 6;
+    const { COMPACT_PREVIEW_LENGTH, MAX_PRESERVED_EXPENSIVE_RESULTS } = EXECUTION_LOOP_DEFAULTS;
     let compactedCount = 0;
     let savedChars = 0;
     const preservedExpensiveIndexes = messages
@@ -69,7 +87,10 @@ export function compactToolOutputs(messages) {
         }
     }
     if (compactedCount > 0 && process.env.DEBUG) {
-        log.debug('Compacted tool outputs', { compactedCount, savedTokens: Math.round(savedChars / 4) });
+        log.debug('Compacted tool outputs', {
+            compactedCount,
+            savedTokens: estimateTokensFromCharCount(savedChars),
+        });
     }
 }
 /**
@@ -86,21 +107,303 @@ export function isRequestedArtifactMissing(requestedArtifact, executedToolNames)
     if (!requestedArtifact)
         return false;
     const artifactWriteTools = ['write_file', 'edit_file', 'apply_patch', 'append_file'];
-    return !artifactWriteTools.some(toolName => executedToolNames.has(toolName));
+    return !artifactWriteTools.some((toolName) => executedToolNames.has(toolName));
 }
 function getOpenTaskSummary(ctx) {
     if (!ctx.taskManager)
         return undefined;
     const tasks = ctx.taskManager.list();
-    const pending = tasks.filter(t => t.status === 'pending').length;
-    const inProgress = tasks.filter(t => t.status === 'in_progress').length;
-    const blocked = tasks.filter(t => t.status === 'pending' && ctx.taskManager?.isBlocked(t.id)).length;
+    const pending = tasks.filter((t) => t.status === 'pending').length;
+    const inProgress = tasks.filter((t) => t.status === 'in_progress').length;
+    const blocked = tasks.filter((t) => t.status === 'pending' && ctx.taskManager?.isBlocked(t.id)).length;
     return { pending, inProgress, blocked };
 }
 function getPendingWithOwnerCount(ctx) {
     if (!ctx.taskManager)
         return 0;
-    return ctx.taskManager.list().filter(t => t.status === 'pending' && !!t.owner).length;
+    return ctx.taskManager.list().filter((t) => t.status === 'pending' && !!t.owner).length;
+}
+/**
+ * Check economics/iteration budget before an iteration.
+ * Returns whether to continue, stop, or whether recovery succeeded.
+ */
+export function checkIterationBudget(deps, messages) {
+    if (deps.economics) {
+        const budgetCheck = deps.economics.checkBudget();
+        const forceTextOnly = budgetCheck.forceTextOnly ?? false;
+        const budgetInjectedPrompt = budgetCheck.injectedPrompt;
+        const budgetAllowsTaskContinuation = budgetCheck.allowTaskContinuation ?? true;
+        deps.traceCollector?.record({
+            type: 'budget.check',
+            data: {
+                iteration: deps.state.iteration,
+                canContinue: budgetCheck.canContinue,
+                percentUsed: budgetCheck.percentUsed,
+                budgetType: budgetCheck.budgetType,
+                budgetMode: budgetCheck.budgetMode,
+                forceTextOnly,
+                allowTaskContinuation: budgetAllowsTaskContinuation,
+                enforcementMode: deps.economics.getBudget().enforcementMode ?? 'strict',
+                tokenUsage: deps.economics.getUsage().tokens,
+                maxTokens: deps.economics.getBudget().maxTokens,
+            },
+        });
+        if (!budgetCheck.canContinue) {
+            // RECOVERY ATTEMPT: Try emergency context reduction
+            const isTokenLimit = budgetCheck.budgetType === 'tokens' || budgetCheck.budgetType === 'cost';
+            const alreadyTriedRecovery = deps.state._recoveryAttempted === true;
+            if (isTokenLimit && !alreadyTriedRecovery) {
+                deps.observability?.logger?.info('Budget limit reached, attempting recovery via context reduction', { reason: budgetCheck.reason, percentUsed: budgetCheck.percentUsed });
+                deps.emit({
+                    type: 'resilience.retry',
+                    reason: 'budget_limit_compaction',
+                    attempt: 1,
+                    maxAttempts: 1,
+                });
+                deps.state.metrics.retryCount = (deps.state.metrics.retryCount ?? 0) + 1;
+                deps.state._recoveryAttempted = true;
+                const tokensBefore = estimateContextTokens(messages);
+                // Step 1: Compact tool outputs aggressively
+                compactToolOutputs(deps.state.messages);
+                // Step 2: Emergency truncation - keep system + last N messages
+                const PRESERVE_RECENT = EXECUTION_LOOP_DEFAULTS.PRESERVE_RECENT;
+                if (messages.length > PRESERVE_RECENT + 2) {
+                    const systemMessage = messages.find((m) => m.role === 'system');
+                    const recentMessages = messages.slice(-PRESERVE_RECENT);
+                    messages.length = 0;
+                    if (systemMessage) {
+                        messages.push(systemMessage);
+                    }
+                    messages.push({
+                        role: 'system',
+                        content: `[CONTEXT REDUCED: Earlier messages were removed to stay within budget. Conversation continues from recent context.]`,
+                    });
+                    messages.push(...recentMessages);
+                    // Inject work log after emergency truncation
+                    if (deps.workLog?.hasContent()) {
+                        messages.push({ role: 'user', content: deps.workLog.toCompactString() });
+                    }
+                    // Update state messages too
+                    deps.state.messages.length = 0;
+                    deps.state.messages.push(...messages);
+                }
+                const tokensAfter = estimateContextTokens(messages);
+                const reduction = Math.round((1 - tokensAfter / tokensBefore) * 100);
+                if (tokensAfter < tokensBefore * 0.8) {
+                    deps.observability?.logger?.info('Context reduction successful, continuing execution', { tokensBefore, tokensAfter, reduction });
+                    deps.emit({ type: 'resilience.recovered', reason: 'budget_limit_compaction', attempts: 1 });
+                    deps.emit({ type: 'compaction.auto', tokensBefore, tokensAfter, messagesCompacted: tokensBefore - tokensAfter });
+                    deps.economics?.updateBaseline(tokensAfter);
+                    return { action: 'recovery_success' };
+                }
+                deps.observability?.logger?.warn('Context reduction insufficient', {
+                    tokensBefore, tokensAfter, reduction,
+                });
+            }
+            // Hard limit reached and recovery failed
+            deps.observability?.logger?.warn('Budget limit reached', {
+                reason: budgetCheck.reason,
+                budgetType: budgetCheck.budgetType,
+            });
+            if (budgetCheck.budgetType === 'iterations') {
+                const totalIter = deps.getTotalIterations();
+                const iterMsg = deps.parentIterations > 0
+                    ? `${deps.state.iteration} + ${deps.parentIterations} parent = ${totalIter}`
+                    : `${deps.state.iteration}`;
+                const reason = `Max iterations reached (${iterMsg})`;
+                deps.emit({ type: 'error', error: reason });
+                return { action: 'stop', result: { success: false, terminationReason: 'max_iterations', failureReason: reason } };
+            }
+            else {
+                const reason = budgetCheck.reason || 'Budget exceeded';
+                deps.emit({ type: 'error', error: reason });
+                return { action: 'stop', result: { success: false, terminationReason: 'budget_limit', failureReason: reason } };
+            }
+        }
+        // Check for soft limits
+        if (budgetCheck.isSoftLimit && budgetCheck.suggestedAction === 'request_extension') {
+            deps.observability?.logger?.info('Approaching budget limit', {
+                reason: budgetCheck.reason,
+                percentUsed: budgetCheck.percentUsed,
+            });
+        }
+        return { action: 'continue', forceTextOnly, budgetInjectedPrompt, budgetAllowsTaskContinuation };
+    }
+    else {
+        // Fallback to simple iteration check
+        if (deps.getTotalIterations() >= deps.maxIterations) {
+            const totalIter = deps.getTotalIterations();
+            const reason = `Max iterations reached (${totalIter})`;
+            deps.observability?.logger?.warn('Max iterations reached', {
+                iteration: deps.state.iteration,
+                parentIterations: deps.parentIterations,
+                total: totalIter,
+            });
+            deps.emit({ type: 'error', error: reason });
+            return { action: 'stop', result: { success: false, terminationReason: 'max_iterations', failureReason: reason } };
+        }
+        return { action: 'continue', forceTextOnly: false, budgetAllowsTaskContinuation: true };
+    }
+}
+/**
+ * Handle auto-compaction of context when approaching token limits.
+ * Returns the compaction status and whether messages were modified.
+ */
+export async function handleAutoCompaction(deps, messages, stateMessages, setCompactionPending) {
+    const currentContextTokens = estimateContextTokens(messages);
+    if (deps.autoCompactionManager) {
+        const compactionResult = await deps.autoCompactionManager.checkAndMaybeCompact({
+            currentTokens: currentContextTokens,
+            messages: messages,
+        });
+        if (compactionResult.status === 'compacted' && compactionResult.compactedMessages) {
+            if (!deps.compactionPending) {
+                setCompactionPending(true);
+                const preCompactionMsg = {
+                    role: 'user',
+                    content: '[SYSTEM] Context compaction is imminent. Summarize your current progress, key findings, and next steps into a single concise message. This will be preserved after compaction.',
+                };
+                messages.push(preCompactionMsg);
+                stateMessages.push(preCompactionMsg);
+                deps.observability?.logger?.info('Pre-compaction agentic turn: injected summary request');
+                return { status: 'compaction_prompt_injected' };
+            }
+            else {
+                setCompactionPending(false);
+                // Replace messages with compacted version
+                messages.length = 0;
+                messages.push(...compactionResult.compactedMessages);
+                stateMessages.length = 0;
+                stateMessages.push(...compactionResult.compactedMessages);
+                // Inject work log after compaction
+                if (deps.workLog?.hasContent()) {
+                    const workLogMessage = { role: 'user', content: deps.workLog.toCompactString() };
+                    messages.push(workLogMessage);
+                    stateMessages.push(workLogMessage);
+                }
+                // Context recovery
+                const recoveryParts = [];
+                if (deps.store) {
+                    const goalsSummary = deps.store.getGoalsSummary();
+                    if (goalsSummary && goalsSummary !== 'No active goals.' && goalsSummary !== 'Goals feature not available.') {
+                        recoveryParts.push(goalsSummary);
+                    }
+                }
+                if (deps.store) {
+                    const juncturesSummary = deps.store.getJuncturesSummary(undefined, 5);
+                    if (juncturesSummary) {
+                        recoveryParts.push(juncturesSummary);
+                    }
+                }
+                if (deps.learningStore) {
+                    const learnings = deps.learningStore.getLearningContext({ maxLearnings: 3 });
+                    if (learnings) {
+                        recoveryParts.push(learnings);
+                    }
+                }
+                if (recoveryParts.length > 0) {
+                    const recoveryMessage = {
+                        role: 'user',
+                        content: `[CONTEXT RECOVERY — Re-injected after compaction]\n\n${recoveryParts.join('\n\n')}`,
+                    };
+                    messages.push(recoveryMessage);
+                    stateMessages.push(recoveryMessage);
+                }
+                const compactionTokensAfter = estimateContextTokens(messages);
+                deps.economics?.updateBaseline(compactionTokensAfter);
+                const compactionEvent = {
+                    type: 'context.compacted',
+                    tokensBefore: currentContextTokens,
+                    tokensAfter: compactionTokensAfter,
+                    recoveryInjected: recoveryParts.length > 0,
+                };
+                deps.emit(compactionEvent);
+                deps.traceCollector?.record({
+                    type: 'context.compacted',
+                    data: {
+                        tokensBefore: currentContextTokens,
+                        tokensAfter: compactionTokensAfter,
+                        recoveryInjected: recoveryParts.length > 0,
+                    },
+                });
+                return { status: 'compacted', tokensBefore: currentContextTokens, tokensAfter: compactionTokensAfter };
+            }
+        }
+        else if (compactionResult.status === 'hard_limit') {
+            const reason = `Context hard limit reached (${Math.round(compactionResult.ratio * 100)}% of max tokens)`;
+            deps.emit({ type: 'error', error: reason });
+            return {
+                status: 'hard_limit',
+                result: { success: false, terminationReason: 'hard_context_limit', failureReason: reason },
+            };
+        }
+    }
+    else if (deps.economics) {
+        // Fallback to simple compaction
+        const currentUsage = deps.economics.getUsage();
+        const budget = deps.economics.getBudget();
+        const percentUsed = (currentUsage.tokens / budget.maxTokens) * 100;
+        if (percentUsed >= 70) {
+            deps.observability?.logger?.info('Proactive compaction triggered', {
+                percentUsed: Math.round(percentUsed),
+                currentTokens: currentUsage.tokens,
+                maxTokens: budget.maxTokens,
+            });
+            compactToolOutputs(stateMessages);
+            return { status: 'simple_compaction_triggered' };
+        }
+    }
+    return { status: 'ok' };
+}
+/**
+ * Guard against mass tool results overflowing the context window.
+ * Truncates tool results that would push total context beyond budget.
+ * Mutates toolResults in-place.
+ */
+export function applyContextOverflowGuard(deps, messages, toolResults) {
+    if (!deps.economics || toolResults.length <= 10)
+        return 0;
+    const preAccumTokens = estimateContextTokens(messages);
+    const budget = deps.economics.getBudget();
+    const availableTokens = budget.maxTokens * EXECUTION_LOOP_DEFAULTS.CONTEXT_SAFETY_RATIO - preAccumTokens;
+    const MAX_TOOL_OUTPUT_CHARS = EXECUTION_LOOP_DEFAULTS.MAX_TOOL_OUTPUT_CHARS;
+    let totalResultTokens = 0;
+    for (const r of toolResults) {
+        const c = typeof r.result === 'string' ? r.result : stableStringify(r.result);
+        totalResultTokens += estimateTokensFromCharCount(Math.min(c.length, MAX_TOOL_OUTPUT_CHARS));
+    }
+    if (totalResultTokens > availableTokens && availableTokens > 0) {
+        log.warn('Tool results would exceed context budget — truncating batch', {
+            resultCount: toolResults.length,
+            estimatedTokens: totalResultTokens,
+            availableTokens: Math.round(availableTokens),
+        });
+        let tokenBudget = availableTokens;
+        for (let i = 0; i < toolResults.length; i++) {
+            const c = typeof toolResults[i].result === 'string'
+                ? toolResults[i].result
+                : stableStringify(toolResults[i].result);
+            const tokens = estimateTokensFromCharCount(Math.min(c.length, MAX_TOOL_OUTPUT_CHARS));
+            if (tokens > tokenBudget) {
+                const skipped = toolResults.length - i;
+                for (let j = i; j < toolResults.length; j++) {
+                    toolResults[j] = {
+                        callId: toolResults[j].callId,
+                        result: `[Result omitted: context overflow guard — ${skipped} of ${toolResults.length} results skipped]`,
+                    };
+                }
+                deps.emit({
+                    type: 'safeguard.context_overflow_guard',
+                    estimatedTokens: totalResultTokens,
+                    maxTokens: budget.maxTokens,
+                    toolResultsSkipped: skipped,
+                });
+                return skipped;
+            }
+            tokenBudget -= tokens;
+        }
+    }
+    return 0;
 }
 // =============================================================================
 // MAIN EXECUTION LOOP
@@ -135,12 +438,8 @@ export async function executeDirectly(task, messages, ctx, mutators) {
     const reflectionConfig = ctx.config.reflection;
     const reflectionEnabled = isFeatureEnabled(reflectionConfig);
     const autoReflect = reflectionEnabled && reflectionConfig.autoReflect;
-    const maxReflectionAttempts = reflectionEnabled
-        ? (reflectionConfig.maxAttempts || 3)
-        : 1;
-    const confidenceThreshold = reflectionEnabled
-        ? (reflectionConfig.confidenceThreshold || 0.8)
-        : 0.8;
+    const maxReflectionAttempts = reflectionEnabled ? reflectionConfig.maxAttempts || 3 : 1;
+    const confidenceThreshold = reflectionEnabled ? reflectionConfig.confidenceThreshold || 0.8 : 0.8;
     let reflectionAttempt = 0;
     let lastResponse = '';
     let incompleteActionRetries = 0;
@@ -194,163 +493,33 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                 }
             }
             // =======================================================================
-            // ECONOMICS CHECK (Token Budget)
+            // ECONOMICS CHECK (Token Budget) — delegated to checkIterationBudget()
             // =======================================================================
             let forceTextOnly = false;
             let budgetInjectedPrompt;
             let budgetAllowsTaskContinuation = true;
-            if (ctx.economics) {
-                const budgetCheck = ctx.economics.checkBudget();
-                forceTextOnly = budgetCheck.forceTextOnly ?? false;
-                budgetInjectedPrompt = budgetCheck.injectedPrompt;
-                budgetAllowsTaskContinuation = budgetCheck.allowTaskContinuation ?? true;
-                // Record budget check in trace for debugging premature death
-                ctx.traceCollector?.record({
-                    type: 'budget.check',
-                    data: {
-                        iteration: ctx.state.iteration,
-                        canContinue: budgetCheck.canContinue,
-                        percentUsed: budgetCheck.percentUsed,
-                        budgetType: budgetCheck.budgetType,
-                        budgetMode: budgetCheck.budgetMode,
-                        forceTextOnly,
-                        allowTaskContinuation: budgetAllowsTaskContinuation,
-                        enforcementMode: ctx.economics.getBudget().enforcementMode ?? 'strict',
-                        tokenUsage: ctx.economics.getUsage().tokens,
-                        maxTokens: ctx.economics.getBudget().maxTokens,
-                    },
-                });
-                if (!budgetCheck.canContinue) {
-                    // RECOVERY ATTEMPT: Try emergency context reduction
-                    const isTokenLimit = budgetCheck.budgetType === 'tokens' || budgetCheck.budgetType === 'cost';
-                    const alreadyTriedRecovery = ctx.state._recoveryAttempted === true;
-                    if (isTokenLimit && !alreadyTriedRecovery) {
-                        ctx.observability?.logger?.info('Budget limit reached, attempting recovery via context reduction', {
-                            reason: budgetCheck.reason,
-                            percentUsed: budgetCheck.percentUsed,
-                        });
-                        ctx.emit({
-                            type: 'resilience.retry',
-                            reason: 'budget_limit_compaction',
-                            attempt: 1,
-                            maxAttempts: 1,
-                        });
-                        ctx.state.metrics.retryCount = (ctx.state.metrics.retryCount ?? 0) + 1;
-                        ctx.state._recoveryAttempted = true;
-                        const tokensBefore = estimateContextTokens(messages);
-                        // Step 1: Compact tool outputs aggressively
-                        compactToolOutputs(ctx.state.messages);
-                        // Step 2: Emergency truncation - keep system + last N messages
-                        const PRESERVE_RECENT = 10;
-                        if (messages.length > PRESERVE_RECENT + 2) {
-                            const systemMessage = messages.find(m => m.role === 'system');
-                            const recentMessages = messages.slice(-(PRESERVE_RECENT));
-                            messages.length = 0;
-                            if (systemMessage) {
-                                messages.push(systemMessage);
-                            }
-                            messages.push({
-                                role: 'system',
-                                content: `[CONTEXT REDUCED: Earlier messages were removed to stay within budget. Conversation continues from recent context.]`,
-                            });
-                            messages.push(...recentMessages);
-                            // Inject work log after emergency truncation
-                            if (ctx.workLog?.hasContent()) {
-                                const workLogMessage = {
-                                    role: 'user',
-                                    content: ctx.workLog.toCompactString(),
-                                };
-                                messages.push(workLogMessage);
-                            }
-                            // Update state messages too
-                            ctx.state.messages.length = 0;
-                            ctx.state.messages.push(...messages);
-                        }
-                        const tokensAfter = estimateContextTokens(messages);
-                        const reduction = Math.round((1 - tokensAfter / tokensBefore) * 100);
-                        if (tokensAfter < tokensBefore * 0.8) {
-                            ctx.observability?.logger?.info('Context reduction successful, continuing execution', {
-                                tokensBefore,
-                                tokensAfter,
-                                reduction,
-                            });
-                            ctx.emit({
-                                type: 'resilience.recovered',
-                                reason: 'budget_limit_compaction',
-                                attempts: 1,
-                            });
-                            ctx.emit({
-                                type: 'compaction.auto',
-                                tokensBefore,
-                                tokensAfter,
-                                messagesCompacted: tokensBefore - tokensAfter,
-                            });
-                            // Update baseline after emergency context reduction so
-                            // incremental token accounting reflects the new context size
-                            ctx.economics?.updateBaseline(tokensAfter);
-                            continue;
-                        }
-                        ctx.observability?.logger?.warn('Context reduction insufficient', {
-                            tokensBefore,
-                            tokensAfter,
-                            reduction,
-                        });
-                    }
-                    // Hard limit reached and recovery failed
-                    ctx.observability?.logger?.warn('Budget limit reached', {
-                        reason: budgetCheck.reason,
-                        budgetType: budgetCheck.budgetType,
-                    });
-                    if (budgetCheck.budgetType === 'iterations') {
-                        const totalIter = ctx.getTotalIterations();
-                        const iterMsg = ctx.parentIterations > 0
-                            ? `${ctx.state.iteration} + ${ctx.parentIterations} parent = ${totalIter}`
-                            : `${ctx.state.iteration}`;
-                        const reason = `Max iterations reached (${iterMsg})`;
-                        ctx.emit({ type: 'error', error: reason });
-                        result = {
-                            success: false,
-                            terminationReason: 'max_iterations',
-                            failureReason: reason,
-                        };
-                    }
-                    else {
-                        const reason = budgetCheck.reason || 'Budget exceeded';
-                        ctx.emit({ type: 'error', error: reason });
-                        result = {
-                            success: false,
-                            terminationReason: 'budget_limit',
-                            failureReason: reason,
-                        };
-                    }
-                    break;
-                }
-                // Check for soft limits and potential extension
-                if (budgetCheck.isSoftLimit && budgetCheck.suggestedAction === 'request_extension') {
-                    ctx.observability?.logger?.info('Approaching budget limit', {
-                        reason: budgetCheck.reason,
-                        percentUsed: budgetCheck.percentUsed,
-                    });
-                }
+            const budgetResult = checkIterationBudget({
+                economics: ctx.economics,
+                getTotalIterations: () => ctx.getTotalIterations(),
+                maxIterations: ctx.config.maxIterations,
+                parentIterations: ctx.parentIterations,
+                state: ctx.state,
+                workLog: ctx.workLog,
+                observability: ctx.observability,
+                traceCollector: ctx.traceCollector,
+                emit: (event) => ctx.emit(event),
+            }, messages);
+            if (budgetResult.action === 'recovery_success') {
+                continue;
+            }
+            else if (budgetResult.action === 'stop') {
+                result = budgetResult.result;
+                break;
             }
             else {
-                // Fallback to simple iteration check
-                if (ctx.getTotalIterations() >= ctx.config.maxIterations) {
-                    const totalIter = ctx.getTotalIterations();
-                    const reason = `Max iterations reached (${totalIter})`;
-                    ctx.observability?.logger?.warn('Max iterations reached', {
-                        iteration: ctx.state.iteration,
-                        parentIterations: ctx.parentIterations,
-                        total: totalIter,
-                    });
-                    ctx.emit({ type: 'error', error: reason });
-                    result = {
-                        success: false,
-                        terminationReason: 'max_iterations',
-                        failureReason: reason,
-                    };
-                    break;
-                }
+                forceTextOnly = budgetResult.forceTextOnly;
+                budgetInjectedPrompt = budgetResult.budgetInjectedPrompt;
+                budgetAllowsTaskContinuation = budgetResult.budgetAllowsTaskContinuation;
             }
             // =======================================================================
             // GRACEFUL WRAPUP CHECK
@@ -396,15 +565,17 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                 }
                 const enrichedMessages = ctx.contextEngineering.injectRecitation(messages, {
                     goal: task,
-                    plan: ctx.state.plan ? {
-                        description: ctx.state.plan.goal || task,
-                        tasks: ctx.state.plan.tasks.map(t => ({
-                            id: t.id,
-                            description: t.description,
-                            status: t.status,
-                        })),
-                        currentTaskIndex: ctx.state.plan.tasks.findIndex(t => t.status === 'in_progress'),
-                    } : undefined,
+                    plan: ctx.state.plan
+                        ? {
+                            description: ctx.state.plan.goal || task,
+                            tasks: ctx.state.plan.tasks.map((t) => ({
+                                id: t.id,
+                                description: t.description,
+                                status: t.status,
+                            })),
+                            currentTaskIndex: ctx.state.plan.tasks.findIndex((t) => t.status === 'in_progress'),
+                        }
+                        : undefined,
                     activeFiles: ctx.economics?.getProgress().filesModified
                         ? [`${ctx.economics.getProgress().filesModified} files modified`]
                         : undefined,
@@ -412,7 +583,9 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                 });
                 if (process.env.DEBUG_LLM) {
                     if (process.env.DEBUG)
-                        log.debug('Recitation after', { messageCount: enrichedMessages?.length ?? 'null/undefined' });
+                        log.debug('Recitation after', {
+                            messageCount: enrichedMessages?.length ?? 'null/undefined',
+                        });
                 }
                 if (enrichedMessages && enrichedMessages !== messages && enrichedMessages.length > 0) {
                     messages.length = 0;
@@ -421,7 +594,7 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                 else if (!enrichedMessages || enrichedMessages.length === 0) {
                     log.warn('Recitation returned empty/null messages, keeping original');
                 }
-                const contextTokens = messages.reduce((sum, m) => sum + (m.content?.length || 0) / 4, 0);
+                const contextTokens = estimateContextTokens(messages);
                 ctx.contextEngineering.updateRecitationFrequency(contextTokens);
             }
             // =======================================================================
@@ -448,7 +621,9 @@ export async function executeDirectly(task, messages, ctx, mutators) {
             // =======================================================================
             // RESUME ORIENTATION — after compaction, nudge the agent to act, not re-summarize
             // =======================================================================
-            const hasCompactionSummary = messages.some(m => m.role === 'system' && typeof m.content === 'string' && m.content.includes('[Conversation Summary'));
+            const hasCompactionSummary = messages.some((m) => m.role === 'system' &&
+                typeof m.content === 'string' &&
+                m.content.includes('[Conversation Summary'));
             if (hasCompactionSummary && ctx.state.iteration <= 2) {
                 messages.push({
                     role: 'user',
@@ -461,31 +636,48 @@ export async function executeDirectly(task, messages, ctx, mutators) {
             if (ctx.injectionBudget) {
                 const proposals = [];
                 if (budgetInjectedPrompt) {
-                    proposals.push({ name: 'budget_warning', priority: 0, maxTokens: 500, content: budgetInjectedPrompt });
+                    proposals.push({
+                        name: 'budget_warning',
+                        priority: 0,
+                        maxTokens: 500,
+                        content: budgetInjectedPrompt,
+                    });
                 }
                 if (ctx.contextEngineering) {
                     const failureCtx = ctx.contextEngineering.getFailureContext(5);
                     if (failureCtx) {
-                        proposals.push({ name: 'failure_context', priority: 2, maxTokens: 300, content: failureCtx });
+                        proposals.push({
+                            name: 'failure_context',
+                            priority: 2,
+                            maxTokens: 300,
+                            content: failureCtx,
+                        });
                     }
                 }
                 if (proposals.length > 0) {
                     const accepted = ctx.injectionBudget.allocate(proposals);
                     const stats = ctx.injectionBudget.getLastStats();
                     if (stats && stats.droppedNames.length > 0 && process.env.DEBUG) {
-                        log.debug('Injection budget dropped items', { droppedNames: stats.droppedNames.join(', '), proposedTokens: stats.proposedTokens, acceptedTokens: stats.acceptedTokens });
+                        log.debug('Injection budget dropped items', {
+                            droppedNames: stats.droppedNames.join(', '),
+                            proposedTokens: stats.proposedTokens,
+                            acceptedTokens: stats.acceptedTokens,
+                        });
                     }
                     if (stats && process.env.DEBUG_LLM) {
-                        log.debug('Injection budget summary', { iteration: ctx.state.iteration, accepted: accepted.length, total: proposals.length, tokens: stats.acceptedTokens });
+                        log.debug('Injection budget summary', {
+                            iteration: ctx.state.iteration,
+                            accepted: accepted.length,
+                            total: proposals.length,
+                            tokens: stats.acceptedTokens,
+                        });
                     }
                 }
             }
             // =======================================================================
             // RESILIENT LLM CALL
             // =======================================================================
-            const resilienceConfig = typeof ctx.config.resilience === 'object'
-                ? ctx.config.resilience
-                : {};
+            const resilienceConfig = typeof ctx.config.resilience === 'object' ? ctx.config.resilience : {};
             const resilienceEnabled = isFeatureEnabled(ctx.config.resilience);
             const MAX_EMPTY_RETRIES = resilienceConfig.maxEmptyRetries ?? 2;
             const MAX_CONTINUATIONS = resilienceConfig.maxContinuations ?? 3;
@@ -537,8 +729,10 @@ export async function executeDirectly(task, messages, ctx, mutators) {
             // skip the expensive LLM call (whose tool calls would be discarded) and
             // go directly to the task continuation gate. Only allowed once per
             // forceTextOnly episode to prevent tight loops.
-            if (forceTextOnly && budgetAllowsTaskContinuation && ctx.taskManager
-                && !ctx.state._lastSkippedLLMIteration) {
+            if (forceTextOnly &&
+                budgetAllowsTaskContinuation &&
+                ctx.taskManager &&
+                !ctx.state._lastSkippedLLMIteration) {
                 const availableTasks = ctx.taskManager.getAvailableTasks();
                 if (availableTasks.length > 0) {
                     log.info('Skipping LLM call — forceTextOnly with tasks available, going to task continuation', {
@@ -546,7 +740,8 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                         iteration: ctx.state.iteration,
                     });
                     // Mark that we skipped so we don't skip again on the next iteration
-                    ctx.state._lastSkippedLLMIteration = ctx.state.iteration;
+                    ctx.state._lastSkippedLLMIteration =
+                        ctx.state.iteration;
                     // Reset forceTextOnly for the next iteration so the task can run normally
                     forceTextOnly = false;
                     const nextTask = availableTasks[0];
@@ -638,7 +833,10 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                 response = await callLLM(messages, ctx);
             }
             // Phase 2: Handle max_tokens truncation with continuation
-            if (resilienceEnabled && AUTO_CONTINUE && response.stopReason === 'max_tokens' && !response.toolCalls?.length) {
+            if (resilienceEnabled &&
+                AUTO_CONTINUE &&
+                response.stopReason === 'max_tokens' &&
+                !response.toolCalls?.length) {
                 let accumulatedContent = response.content || '';
                 while (continuations < MAX_CONTINUATIONS && response.stopReason === 'max_tokens') {
                     continuations++;
@@ -682,10 +880,10 @@ export async function executeDirectly(task, messages, ctx, mutators) {
             if (resilienceEnabled && response.stopReason === 'max_tokens' && response.toolCalls?.length) {
                 ctx.emit({
                     type: 'resilience.truncated_tool_call',
-                    toolNames: response.toolCalls.map(tc => tc.name),
+                    toolNames: response.toolCalls.map((tc) => tc.name),
                 });
                 ctx.observability?.logger?.warn('Tool call truncated at max_tokens', {
-                    toolNames: response.toolCalls.map(tc => tc.name),
+                    toolNames: response.toolCalls.map((tc) => tc.name),
                     outputTokens: response.usage?.outputTokens,
                 });
                 const truncatedResponse = response;
@@ -728,9 +926,12 @@ export async function executeDirectly(task, messages, ctx, mutators) {
             ctx.state.messages.push(assistantMessage);
             lastResponse = response.content || (response.thinking ? response.thinking : '');
             // Plan mode: capture exploration findings
-            if (ctx.modeManager.getMode() === 'plan' && response.content && response.content.length > 50) {
-                const hasReadOnlyTools = response.toolCalls?.every(tc => ['read_file', 'list_files', 'glob', 'grep', 'search', 'mcp_'].some(prefix => tc.name.startsWith(prefix) || tc.name === prefix));
-                if (hasReadOnlyTools && !response.content.match(/^(Let me|I'll|I will|I need to|First,)/i)) {
+            if (ctx.modeManager.getMode() === 'plan' &&
+                response.content &&
+                response.content.length > 50) {
+                const hasReadOnlyTools = response.toolCalls?.every((tc) => ['read_file', 'list_files', 'glob', 'grep', 'search', 'mcp_'].some((prefix) => tc.name.startsWith(prefix) || tc.name === prefix));
+                if (hasReadOnlyTools &&
+                    !response.content.match(/^(Let me|I'll|I will|I need to|First,)/i)) {
                     ctx.pendingPlanManager.appendExplorationFinding(response.content.slice(0, 1000));
                 }
             }
@@ -751,10 +952,10 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                 const missingRequiredArtifact = ENFORCE_REQUESTED_ARTIFACTS
                     ? isRequestedArtifactMissing(requestedArtifact, executedToolNames)
                     : false;
-                const shouldRecoverIncompleteAction = resilienceEnabled
-                    && INCOMPLETE_ACTION_RECOVERY
-                    && !forceTextOnly
-                    && (incompleteAction || missingRequiredArtifact);
+                const shouldRecoverIncompleteAction = resilienceEnabled &&
+                    INCOMPLETE_ACTION_RECOVERY &&
+                    !forceTextOnly &&
+                    (incompleteAction || missingRequiredArtifact);
                 if (shouldRecoverIncompleteAction) {
                     ctx.emit({
                         type: 'completion.before',
@@ -847,15 +1048,20 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                     incompleteActionRetries = 0;
                 }
                 // TypeScript compilation gate — block completion if TS files edited and errors exist
-                if (ctx.typeCheckerState?.tsconfigDir
-                    && !forceTextOnly
-                    && (ctx.typeCheckerState.tsEditsSinceLastCheck > 0 || !ctx.typeCheckerState.hasRunOnce)) {
+                if (ctx.typeCheckerState?.tsconfigDir &&
+                    !forceTextOnly &&
+                    (ctx.typeCheckerState.tsEditsSinceLastCheck > 0 || !ctx.typeCheckerState.hasRunOnce)) {
                     const tscResult = await runTypeCheck(ctx.typeCheckerState.tsconfigDir);
                     ctx.typeCheckerState.tsEditsSinceLastCheck = 0;
                     ctx.typeCheckerState.lastResult = tscResult;
                     ctx.typeCheckerState.hasRunOnce = true;
                     ctx.verificationGate?.recordCompilationResult(tscResult.success, tscResult.errorCount);
-                    ctx.emit({ type: 'diagnostics.tsc-check', errorCount: tscResult.errorCount, duration: tscResult.duration, trigger: 'completion' });
+                    ctx.emit({
+                        type: 'diagnostics.tsc-check',
+                        errorCount: tscResult.errorCount,
+                        duration: tscResult.duration,
+                        trigger: 'completion',
+                    });
                     if (!tscResult.success) {
                         const vState = ctx.verificationGate?.getState();
                         const maxCompNudges = 8;
@@ -865,7 +1071,10 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                             messages.push(nudgeMessage);
                             ctx.state.messages.push(nudgeMessage);
                             ctx.verificationGate?.incrementCompilationNudge();
-                            log.info('Compilation gate blocked completion', { count: tscResult.errorCount, nudgeCount: ctx.verificationGate?.getState().compilationNudgeCount });
+                            log.info('Compilation gate blocked completion', {
+                                count: tscResult.errorCount,
+                                nudgeCount: ctx.verificationGate?.getState().compilationNudgeCount,
+                            });
                             ctx.emit({
                                 type: 'iteration.after',
                                 iteration: ctx.state.iteration,
@@ -995,7 +1204,9 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                         }
                         const reasons = [
                             `Open tasks remain: ${openTasks.pending} pending, ${openTasks.inProgress} in_progress`,
-                            openTasks.blocked > 0 ? `${openTasks.blocked} pending tasks are currently blocked` : '',
+                            openTasks.blocked > 0
+                                ? `${openTasks.blocked} pending tasks are currently blocked`
+                                : '',
                         ].filter(Boolean);
                         ctx.emit({
                             type: 'completion.blocked',
@@ -1025,7 +1236,7 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                 log.warn('Tool call explosion detected — capping', {
                     requested: toolCalls.length,
                     cap: maxToolCallsPerResponse,
-                    toolNames: [...new Set(toolCalls.map(tc => tc.name))],
+                    toolNames: [...new Set(toolCalls.map((tc) => tc.name))],
                 });
                 ctx.emit({
                     type: 'safeguard.tool_call_cap',
@@ -1052,7 +1263,9 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                 // Record in work log
                 const toolOutput = result?.result && typeof result.result === 'object' && 'output' in result.result
                     ? String(result.result.output)
-                    : typeof result?.result === 'string' ? result.result : undefined;
+                    : typeof result?.result === 'string'
+                        ? result.result
+                        : undefined;
                 ctx.workLog?.recordToolExecution(toolCall.name, toolCall.arguments, toolOutput);
                 // Record in verification gate
                 if (ctx.verificationGate) {
@@ -1060,9 +1273,11 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                         const toolRes = result?.result;
                         const output = toolRes && typeof toolRes === 'object' && 'output' in toolRes
                             ? String(toolRes.output)
-                            : typeof toolRes === 'string' ? toolRes : '';
+                            : typeof toolRes === 'string'
+                                ? toolRes
+                                : '';
                         const exitCode = toolRes && typeof toolRes === 'object' && toolRes.metadata
-                            ? toolRes.metadata.exitCode ?? null
+                            ? (toolRes.metadata.exitCode ?? null)
                             : null;
                         ctx.verificationGate.recordBashExecution(String(toolCall.arguments.command || ''), output, exitCode);
                     }
@@ -1071,7 +1286,9 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                     }
                 }
                 // Phase 5.1: Post-edit syntax validation + AST cache invalidation
-                if (['write_file', 'edit_file'].includes(toolCall.name) && result?.result && result.result.success) {
+                if (['write_file', 'edit_file'].includes(toolCall.name) &&
+                    result?.result &&
+                    result.result.success) {
                     const filePath = String(toolCall.arguments.path || '');
                     if (filePath) {
                         // Invalidate stale AST cache entry so next analysis/validation reparses
@@ -1086,18 +1303,26 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                                 try {
                                     await ctx.codebaseContext.updateFile(filePath, content);
                                 }
-                                catch { /* non-blocking */ }
+                                catch {
+                                    /* non-blocking */
+                                }
                             }
                             const validation = validateSyntax(content, filePath);
                             if (!validation.valid && result.result && typeof result.result === 'object') {
                                 const errorSummary = validation.errors
                                     .slice(0, 3)
-                                    .map(e => `  L${e.line}:${e.column}: ${e.message}`)
+                                    .map((e) => `  L${e.line}:${e.column}: ${e.message}`)
                                     .join('\n');
-                                result.result.output += `\n\n⚠ Syntax validation warning:\n${errorSummary}`;
+                                result.result.output +=
+                                    `\n\n⚠ Syntax validation warning:\n${errorSummary}`;
                                 // Emit diagnostic events for each syntax error
                                 for (const err of validation.errors.slice(0, 5)) {
-                                    ctx.emit({ type: 'diagnostics.syntax-error', file: filePath, line: err.line, message: err.message });
+                                    ctx.emit({
+                                        type: 'diagnostics.syntax-error',
+                                        file: filePath,
+                                        line: err.line,
+                                        message: err.message,
+                                    });
                                 }
                             }
                         }
@@ -1112,180 +1337,48 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                 }
             }
             // Add tool results to messages (with truncation and proactive budget management)
-            const MAX_TOOL_OUTPUT_CHARS = 8000;
-            // PROACTIVE BUDGET CHECK
-            const currentContextTokens = estimateContextTokens(messages);
-            if (ctx.autoCompactionManager) {
-                const compactionResult = await ctx.autoCompactionManager.checkAndMaybeCompact({
-                    currentTokens: currentContextTokens,
-                    messages: messages,
-                });
-                if (compactionResult.status === 'compacted' && compactionResult.compactedMessages) {
-                    if (!ctx.compactionPending) {
-                        mutators.setCompactionPending(true);
-                        const preCompactionMsg = {
-                            role: 'user',
-                            content: '[SYSTEM] Context compaction is imminent. Summarize your current progress, key findings, and next steps into a single concise message. This will be preserved after compaction.',
-                        };
-                        messages.push(preCompactionMsg);
-                        ctx.state.messages.push(preCompactionMsg);
-                        ctx.observability?.logger?.info('Pre-compaction agentic turn: injected summary request');
-                    }
-                    else {
-                        mutators.setCompactionPending(false);
-                        // Pre-compaction checkpoint
-                        // NOTE: autoCheckpoint is called via the agent's method, not directly here
-                        // The agent wires this through the mutators pattern
-                        // Replace messages with compacted version
-                        messages.length = 0;
-                        messages.push(...compactionResult.compactedMessages);
-                        ctx.state.messages.length = 0;
-                        ctx.state.messages.push(...compactionResult.compactedMessages);
-                        // Inject work log after compaction
-                        if (ctx.workLog?.hasContent()) {
-                            const workLogMessage = {
-                                role: 'user',
-                                content: ctx.workLog.toCompactString(),
-                            };
-                            messages.push(workLogMessage);
-                            ctx.state.messages.push(workLogMessage);
-                        }
-                        // Context recovery
-                        const recoveryParts = [];
-                        if (ctx.store) {
-                            const goalsSummary = ctx.store.getGoalsSummary();
-                            if (goalsSummary && goalsSummary !== 'No active goals.' && goalsSummary !== 'Goals feature not available.') {
-                                recoveryParts.push(goalsSummary);
-                            }
-                        }
-                        if (ctx.store) {
-                            const juncturesSummary = ctx.store.getJuncturesSummary(undefined, 5);
-                            if (juncturesSummary) {
-                                recoveryParts.push(juncturesSummary);
-                            }
-                        }
-                        if (ctx.learningStore) {
-                            const learnings = ctx.learningStore.getLearningContext({ maxLearnings: 3 });
-                            if (learnings) {
-                                recoveryParts.push(learnings);
-                            }
-                        }
-                        if (recoveryParts.length > 0) {
-                            const recoveryMessage = {
-                                role: 'user',
-                                content: `[CONTEXT RECOVERY — Re-injected after compaction]\n\n${recoveryParts.join('\n\n')}`,
-                            };
-                            messages.push(recoveryMessage);
-                            ctx.state.messages.push(recoveryMessage);
-                        }
-                        // Emit compaction event
-                        const compactionTokensAfter = estimateContextTokens(messages);
-                        const compactionRecoveryInjected = recoveryParts.length > 0;
-                        // Update baseline after compaction so incremental token
-                        // accounting reflects the reduced context size
-                        ctx.economics?.updateBaseline(compactionTokensAfter);
-                        const compactionEvent = {
-                            type: 'context.compacted',
-                            tokensBefore: currentContextTokens,
-                            tokensAfter: compactionTokensAfter,
-                            recoveryInjected: compactionRecoveryInjected,
-                        };
-                        ctx.emit(compactionEvent);
-                        if (ctx.traceCollector) {
-                            ctx.traceCollector.record({
-                                type: 'context.compacted',
-                                data: {
-                                    tokensBefore: currentContextTokens,
-                                    tokensAfter: compactionTokensAfter,
-                                    recoveryInjected: compactionRecoveryInjected,
-                                },
-                            });
-                        }
-                    }
-                }
-                else if (compactionResult.status === 'hard_limit') {
-                    const reason = `Context hard limit reached (${Math.round(compactionResult.ratio * 100)}% of max tokens)`;
-                    ctx.emit({ type: 'error', error: reason });
-                    result = {
-                        success: false,
-                        terminationReason: 'hard_context_limit',
-                        failureReason: reason,
-                    };
-                    break;
-                }
-            }
-            else if (ctx.economics) {
-                // Fallback to simple compaction
-                const currentUsage = ctx.economics.getUsage();
-                const budget = ctx.economics.getBudget();
-                const percentUsed = (currentUsage.tokens / budget.maxTokens) * 100;
-                if (percentUsed >= 70) {
-                    ctx.observability?.logger?.info('Proactive compaction triggered', {
-                        percentUsed: Math.round(percentUsed),
-                        currentTokens: currentUsage.tokens,
-                        maxTokens: budget.maxTokens,
-                    });
-                    compactToolOutputs(ctx.state.messages);
-                }
-            }
-            // SAFEGUARD: Aggregate context guard — prevent mass small results from overflowing
-            if (ctx.economics && toolResults.length > 10) {
-                const preAccumTokens = estimateContextTokens(messages);
-                const budget = ctx.economics.getBudget();
-                const availableTokens = budget.maxTokens * 0.90 - preAccumTokens;
-                // Estimate total result tokens
-                let totalResultTokens = 0;
-                for (const r of toolResults) {
-                    const c = typeof r.result === 'string' ? r.result : stableStringify(r.result);
-                    totalResultTokens += Math.ceil(Math.min(c.length, MAX_TOOL_OUTPUT_CHARS) / 4);
-                }
-                if (totalResultTokens > availableTokens && availableTokens > 0) {
-                    log.warn('Tool results would exceed context budget — truncating batch', {
-                        resultCount: toolResults.length,
-                        estimatedTokens: totalResultTokens,
-                        availableTokens: Math.round(availableTokens),
-                    });
-                    let tokenBudget = availableTokens;
-                    for (let i = 0; i < toolResults.length; i++) {
-                        const c = typeof toolResults[i].result === 'string'
-                            ? toolResults[i].result
-                            : stableStringify(toolResults[i].result);
-                        const tokens = Math.ceil(Math.min(c.length, MAX_TOOL_OUTPUT_CHARS) / 4);
-                        if (tokens > tokenBudget) {
-                            const skipped = toolResults.length - i;
-                            for (let j = i; j < toolResults.length; j++) {
-                                toolResults[j] = {
-                                    callId: toolResults[j].callId,
-                                    result: `[Result omitted: context overflow guard — ${skipped} of ${toolResults.length} results skipped]`,
-                                };
-                            }
-                            ctx.emit({
-                                type: 'safeguard.context_overflow_guard',
-                                estimatedTokens: totalResultTokens,
-                                maxTokens: budget.maxTokens,
-                                toolResultsSkipped: skipped,
-                            });
-                            break;
-                        }
-                        tokenBudget -= tokens;
-                    }
-                }
+            const MAX_TOOL_OUTPUT_CHARS = EXECUTION_LOOP_DEFAULTS.MAX_TOOL_OUTPUT_CHARS;
+            // PROACTIVE BUDGET CHECK — delegate to extracted function
+            const compactionStatus = await handleAutoCompaction({
+                autoCompactionManager: ctx.autoCompactionManager ?? null,
+                compactionPending: ctx.compactionPending,
+                economics: ctx.economics,
+                workLog: ctx.workLog,
+                store: ctx.store,
+                learningStore: ctx.learningStore,
+                observability: ctx.observability,
+                traceCollector: ctx.traceCollector,
+                emit: (event) => ctx.emit(event),
+            }, messages, ctx.state.messages, (v) => mutators.setCompactionPending(v));
+            if (compactionStatus.status === 'hard_limit') {
+                result = compactionStatus.result;
+                break;
             }
-            const toolCallNameById = new Map(toolCalls.map(tc => [tc.id, tc.name]));
+            // SAFEGUARD: Aggregate context guard — delegate to extracted function
+            applyContextOverflowGuard({ economics: ctx.economics, emit: (event) => ctx.emit(event) }, messages, toolResults);
+            const toolCallNameById = new Map(toolCalls.map((tc) => [tc.id, tc.name]));
             for (const result of toolResults) {
-                let content = typeof result.result === 'string' ? result.result : stableStringify(result.result);
+                let content = typeof result.result === 'string'
+                    ? result.result
+                    : ctx.contextEngineering
+                        ? ctx.contextEngineering.serialize(result.result)
+                        : stableStringify(result.result);
                 const sourceToolName = toolCallNameById.get(result.callId);
                 const isExpensiveResult = sourceToolName === 'spawn_agent' || sourceToolName === 'spawn_agents_parallel';
-                const effectiveMaxChars = isExpensiveResult ? MAX_TOOL_OUTPUT_CHARS * 2 : MAX_TOOL_OUTPUT_CHARS;
+                const effectiveMaxChars = isExpensiveResult
+                    ? MAX_TOOL_OUTPUT_CHARS * 2
+                    : MAX_TOOL_OUTPUT_CHARS;
                 if (content.length > effectiveMaxChars) {
-                    content = content.slice(0, effectiveMaxChars) + `\n\n... [truncated ${content.length - effectiveMaxChars} chars]`;
+                    content =
+                        content.slice(0, effectiveMaxChars) +
+                            `\n\n... [truncated ${content.length - effectiveMaxChars} chars]`;
                 }
                 // Check if adding this result would exceed budget
                 if (ctx.economics) {
                     const estimatedNewTokens = estimateTokenCount(content);
                     const currentCtxTokens = estimateContextTokens(messages);
                     const budget = ctx.economics.getBudget();
-                    if (currentCtxTokens + estimatedNewTokens > budget.maxTokens * 0.95) {
+                    if (currentCtxTokens + estimatedNewTokens > budget.maxTokens * EXECUTION_LOOP_DEFAULTS.PER_RESULT_BUDGET_RATIO) {
                         ctx.observability?.logger?.warn('Skipping tool result to stay within budget', {
                             toolCallId: result.callId,
                             estimatedTokens: estimatedNewTokens,
@@ -1320,16 +1413,21 @@ export async function executeDirectly(task, messages, ctx, mutators) {
                 ctx.state.messages.push(toolMessage);
             }
             // Periodic TypeScript compilation check (every 5 TS edits)
-            const TYPE_CHECK_EDIT_THRESHOLD = 5;
-            if (ctx.typeCheckerState?.tsconfigDir
-                && ctx.typeCheckerState.tsEditsSinceLastCheck >= TYPE_CHECK_EDIT_THRESHOLD
-                && !forceTextOnly) {
+            const TYPE_CHECK_EDIT_THRESHOLD = EXECUTION_LOOP_DEFAULTS.TYPE_CHECK_EDIT_THRESHOLD;
+            if (ctx.typeCheckerState?.tsconfigDir &&
+                ctx.typeCheckerState.tsEditsSinceLastCheck >= TYPE_CHECK_EDIT_THRESHOLD &&
+                !forceTextOnly) {
                 const tscResult = await runTypeCheck(ctx.typeCheckerState.tsconfigDir);
                 ctx.typeCheckerState.tsEditsSinceLastCheck = 0;
                 ctx.typeCheckerState.lastResult = tscResult;
                 ctx.typeCheckerState.hasRunOnce = true;
                 ctx.verificationGate?.recordCompilationResult(tscResult.success, tscResult.errorCount);
-                ctx.emit({ type: 'diagnostics.tsc-check', errorCount: tscResult.errorCount, duration: tscResult.duration, trigger: 'periodic' });
+                ctx.emit({
+                    type: 'diagnostics.tsc-check',
+                    errorCount: tscResult.errorCount,
+                    duration: tscResult.duration,
+                    trigger: 'periodic',
+                });
                 if (!tscResult.success) {
                     const nudge = formatTypeCheckNudge(tscResult);
                     const infoMsg = { role: 'user', content: nudge };