attocode 0.1.6 → 0.1.8

package/dist/src/agent.js

@@ -18,10 +18,10 @@
  * - Execution Policies (Lesson 23)
  * - Thread Management (Lesson 24)
  */
-import { buildConfig, isFeatureEnabled, getEnabledFeatures, } from './defaults.js';
-import { createModeManager, formatModeList, parseMode, } from './modes.js';
+import { buildConfig, isFeatureEnabled, getEnabledFeatures, getSubagentTimeout, getSubagentMaxIterations, } from './defaults.js';
+import { createModeManager, formatModeList, parseMode, calculateTaskSimilarity, SUBAGENT_PLAN_MODE_ADDITION, } from './modes.js';
 import { createLSPFileTools, } from './agent-tools/index.js';
-import { HookManager, MemoryManager, PlanningManager, ObservabilityManager, SafetyManager, RoutingManager, MultiAgentManager, ReActManager, ExecutionPolicyManager, ThreadManager, RulesManager, DEFAULT_RULE_SOURCES, ExecutionEconomicsManager, STANDARD_BUDGET, AgentRegistry, filterToolsForAgent, formatAgentList, createCancellationManager, isCancellationError, createTimeoutToken, createLinkedToken, race, createResourceManager, createLSPManager, createSemanticCacheManager, createSkillManager, formatSkillList, createContextEngineering, stableStringify, createCodebaseContext, buildContextFromChunks, createPendingPlanManager, createInteractivePlanner, createRecursiveContext, createLearningStore, createCompactor, createAutoCompactionManager, createFileChangeTracker, createCapabilitiesRegistry, createSharedBlackboard, } from './integrations/index.js';
+import { HookManager, MemoryManager, PlanningManager, ObservabilityManager, SafetyManager, RoutingManager, MultiAgentManager, ReActManager, ExecutionPolicyManager, ThreadManager, RulesManager, DEFAULT_RULE_SOURCES, ExecutionEconomicsManager, STANDARD_BUDGET, SUBAGENT_BUDGET, TIMEOUT_WRAPUP_PROMPT, AgentRegistry, filterToolsForAgent, formatAgentList, createCancellationManager, isCancellationError, createLinkedToken, createGracefulTimeout, race, createResourceManager, createLSPManager, createSemanticCacheManager, createSkillManager, formatSkillList, createContextEngineering, stableStringify, createCodebaseContext, buildContextFromChunks, createPendingPlanManager, createInteractivePlanner, createRecursiveContext, createLearningStore, createCompactor, createAutoCompactionManager, createFileChangeTracker, createCapabilitiesRegistry, createSharedBlackboard, createTaskManager, } from './integrations/index.js';
 // Lesson 26: Tracing & Evaluation integration
 import { createTraceCollector } from './tracing/trace-collector.js';
 // Model registry for context window limits
@@ -29,6 +29,8 @@ import { modelRegistry } from './costs/index.js';
 import { getModelContextLength } from './integrations/openrouter-pricing.js';
 // Spawn agent tools for LLM-driven subagent delegation
 import { createBoundSpawnAgentTool, createBoundSpawnAgentsParallelTool, } from './tools/agent.js';
+// Task tools for Claude Code-style task management
+import { createTaskTools, } from './tools/tasks.js';
 // =============================================================================
 // PRODUCTION AGENT
 // =============================================================================
@@ -72,15 +74,25 @@ export class ProductionAgent {
     capabilitiesRegistry = null;
     toolResolver = null;
     blackboard = null;
+    taskManager = null;
+    store = null;
     // Duplicate spawn prevention - tracks recently spawned tasks to prevent doom loops
     // Map<taskKey, { timestamp: number; result: string; queuedChanges: number }>
     spawnedTasks = new Map();
     static SPAWN_DEDUP_WINDOW_MS = 60000; // 60 seconds
     // Parent iteration tracking for total budget calculation
     parentIterations = 0;
+    // External cancellation token (for subagent timeout propagation)
+    // When set, the agent will check this token in addition to its own cancellation manager
+    externalCancellationToken = null;
+    // Graceful wrapup support (for subagent timeout wrapup phase)
+    wrapupRequested = false;
+    wrapupReason = null;
     // Initialization tracking
     initPromises = [];
     initComplete = false;
+    // Event listener cleanup tracking (prevents memory leaks in long sessions)
+    unsubscribers = [];
     // State
     state = {
         status: 'idle',
@@ -95,6 +107,10 @@ export class ProductionAgent {
             llmCalls: 0,
             toolCalls: 0,
             duration: 0,
+            successCount: 0,
+            failureCount: 0,
+            cancelCount: 0,
+            retryCount: 0,
         },
         iteration: 0,
     };
@@ -221,11 +237,13 @@ export class ProductionAgent {
             }));
         }
         // Economics System (Token Budget) - always enabled
+        // Use custom budget if provided (subagents use SUBAGENT_BUDGET), otherwise STANDARD_BUDGET
+        const baseBudget = this.config.budget ?? STANDARD_BUDGET;
         this.economics = new ExecutionEconomicsManager({
-            ...STANDARD_BUDGET,
+            ...baseBudget,
             // Use maxIterations from config as absolute safety cap
             maxIterations: this.config.maxIterations,
-            targetIterations: Math.min(20, this.config.maxIterations),
+            targetIterations: Math.min(baseBudget.targetIterations ?? 20, this.config.maxIterations),
         });
         // Agent Registry - always enabled for subagent support
         this.agentRegistry = new AgentRegistry();
@@ -234,20 +252,39 @@ export class ProductionAgent {
             console.warn('[ProductionAgent] Failed to load user agents:', err);
         }));
         // Register spawn_agent tool so LLM can delegate to subagents
-        const boundSpawnTool = createBoundSpawnAgentTool((name, task) => this.spawnAgent(name, task));
+        const boundSpawnTool = createBoundSpawnAgentTool((name, task, constraints) => this.spawnAgent(name, task, constraints));
         this.tools.set(boundSpawnTool.name, boundSpawnTool);
         // Register spawn_agents_parallel tool for parallel subagent execution
         const boundParallelSpawnTool = createBoundSpawnAgentsParallelTool((tasks) => this.spawnAgentsParallel(tasks));
         this.tools.set(boundParallelSpawnTool.name, boundParallelSpawnTool);
+        // Task Manager - Claude Code-style task system for coordination
+        this.taskManager = createTaskManager();
+        // Forward task events (with cleanup tracking for EventEmitter-based managers)
+        const taskCreatedHandler = (data) => {
+            this.emit({ type: 'task.created', task: data.task });
+        };
+        this.taskManager.on('task.created', taskCreatedHandler);
+        this.unsubscribers.push(() => this.taskManager?.off('task.created', taskCreatedHandler));
+        const taskUpdatedHandler = (data) => {
+            this.emit({ type: 'task.updated', task: data.task });
+        };
+        this.taskManager.on('task.updated', taskUpdatedHandler);
+        this.unsubscribers.push(() => this.taskManager?.off('task.updated', taskUpdatedHandler));
+        // Register task tools
+        const taskTools = createTaskTools(this.taskManager);
+        for (const tool of taskTools) {
+            this.tools.set(tool.name, tool);
+        }
         // Cancellation Support
         if (isFeatureEnabled(this.config.cancellation)) {
             this.cancellation = createCancellationManager();
-            // Forward cancellation events
-            this.cancellation.subscribe(event => {
+            // Forward cancellation events (with cleanup tracking)
+            const unsubCancellation = this.cancellation.subscribe(event => {
                 if (event.type === 'cancellation.requested') {
                     this.emit({ type: 'cancellation.requested', reason: event.reason });
                 }
             });
+            this.unsubscribers.push(unsubCancellation);
         }
         // Resource Monitoring
         if (isFeatureEnabled(this.config.resources)) {
@@ -278,8 +315,8 @@ export class ProductionAgent {
                 maxSize: this.config.semanticCache.maxSize,
                 ttl: this.config.semanticCache.ttl,
             });
-            // Forward cache events
-            this.semanticCache.subscribe(event => {
+            // Forward cache events (with cleanup tracking)
+            const unsubSemanticCache = this.semanticCache.subscribe(event => {
                 if (event.type === 'cache.hit') {
                     this.emit({ type: 'cache.hit', query: event.query, similarity: event.similarity });
                 }
@@ -290,6 +327,7 @@ export class ProductionAgent {
                     this.emit({ type: 'cache.set', query: event.query });
                 }
             });
+            this.unsubscribers.push(unsubSemanticCache);
         }
         // Skills Support
         if (isFeatureEnabled(this.config.skills)) {
@@ -341,8 +379,8 @@ export class ProductionAgent {
                 this.codebaseContext.setLSPManager(this.lspManager);
             }
         }
-        // Forward context engineering events
-        this.contextEngineering.on(event => {
+        // Forward context engineering events (with cleanup tracking)
+        const unsubContextEngineering = this.contextEngineering.on(event => {
             switch (event.type) {
                 case 'failure.recorded':
                     this.observability?.logger?.warn('Failure recorded', {
@@ -364,6 +402,7 @@ export class ProductionAgent {
                     break;
             }
         });
+        this.unsubscribers.push(unsubContextEngineering);
         // Interactive Planning (conversational + editable planning)
         if (isFeatureEnabled(this.config.interactivePlanning)) {
             const interactiveConfig = typeof this.config.interactivePlanning === 'object'
@@ -375,8 +414,8 @@ export class ProductionAgent {
                 maxCheckpoints: 20,
                 autoPauseAtDecisions: true,
             });
-            // Forward planner events to observability
-            this.interactivePlanner.on(event => {
+            // Forward planner events to observability (with cleanup tracking)
+            const unsubInteractivePlanner = this.interactivePlanner.on(event => {
                 switch (event.type) {
                     case 'plan.created':
                         this.observability?.logger?.info('Interactive plan created', {
@@ -400,6 +439,7 @@ export class ProductionAgent {
                         break;
                 }
             });
+            this.unsubscribers.push(unsubInteractivePlanner);
         }
         // Recursive Context (RLM - Recursive Language Models)
         // Enables on-demand context exploration for large codebases
@@ -416,8 +456,8 @@ export class ProductionAgent {
             });
             // Note: File system source should be registered when needed with proper glob/readFile functions
             // This is deferred to allow flexible configuration
-            // Forward RLM events
-            this.recursiveContext.on(event => {
+            // Forward RLM events (with cleanup tracking)
+            const unsubRecursiveContext = this.recursiveContext.on(event => {
                 switch (event.type) {
                     case 'process.started':
                         this.observability?.logger?.debug('RLM process started', {
@@ -444,6 +484,7 @@ export class ProductionAgent {
                         break;
                 }
             });
+            this.unsubscribers.push(unsubRecursiveContext);
         }
         // Learning Store (cross-session learning from failures)
         // Connects to the failure tracker in contextEngineering for automatic learning extraction
@@ -464,8 +505,8 @@ export class ProductionAgent {
                     this.learningStore.connectFailureTracker(failureTracker);
                 }
             }
-            // Forward learning events to observability
-            this.learningStore.on(event => {
+            // Forward learning events to observability (with cleanup tracking)
+            const unsubLearningStore = this.learningStore.on(event => {
                 switch (event.type) {
                     case 'learning.proposed':
                         this.observability?.logger?.info('Learning proposed', {
@@ -503,6 +544,7 @@ export class ProductionAgent {
                         break;
                 }
             });
+            this.unsubscribers.push(unsubLearningStore);
         }
         // Auto-Compaction Manager (sophisticated context compaction)
         // Uses the Compactor for LLM-based summarization with threshold monitoring
@@ -565,8 +607,8 @@ export class ProductionAgent {
                 maxContextTokens, // Dynamic from model registry or config
                 compactHandler, // Use reversible compaction when contextEngineering is available
             });
-            // Forward compactor events to observability
-            this.compactor.on(event => {
+            // Forward compactor events to observability (with cleanup tracking)
+            const unsubCompactor = this.compactor.on(event => {
                 switch (event.type) {
                     case 'compaction.start':
                         this.observability?.logger?.info('Compaction started', {
@@ -587,8 +629,9 @@ export class ProductionAgent {
                         break;
                 }
             });
-            // Forward auto-compaction events
-            this.autoCompactionManager.on((event) => {
+            this.unsubscribers.push(unsubCompactor);
+            // Forward auto-compaction events (with cleanup tracking)
+            const unsubAutoCompaction = this.autoCompactionManager.on((event) => {
                 switch (event.type) {
                     case 'autocompaction.warning':
                         this.observability?.logger?.warn('Context approaching limit', {
@@ -635,6 +678,7 @@ export class ProductionAgent {
                         break;
                 }
             });
+            this.unsubscribers.push(unsubAutoCompaction);
         }
         // Note: FileChangeTracker requires a database instance which is not
         // available at this point. Use initFileChangeTracker() to enable it
@@ -723,6 +767,7 @@ export class ProductionAgent {
             // Finalize
             const duration = Date.now() - startTime;
             this.state.metrics.duration = duration;
+            this.state.metrics.successCount = (this.state.metrics.successCount ?? 0) + 1;
             await this.observability?.tracer?.endTrace();
             const result = {
                 success: true,
@@ -753,6 +798,7 @@ export class ProductionAgent {
                 const cleanupDuration = Date.now() - cleanupStart;
                 this.emit({ type: 'cancellation.completed', cleanupDuration });
                 this.observability?.logger?.info('Agent cancelled', { reason: error.message, cleanupDuration });
+                this.state.metrics.cancelCount = (this.state.metrics.cancelCount ?? 0) + 1;
                 // Lesson 26: End trace capture on cancellation
                 if (this.traceCollector?.isTaskActive()) {
                     await this.traceCollector.endTask({ success: false, failureReason: `Cancelled: ${error.message}` });
@@ -771,6 +817,7 @@ export class ProductionAgent {
             }
             this.observability?.tracer?.recordError(error);
             await this.observability?.tracer?.endTrace();
+            this.state.metrics.failureCount = (this.state.metrics.failureCount ?? 0) + 1;
             this.emit({ type: 'error', error: error.message });
             this.observability?.logger?.error('Agent failed', { error: error.message });
             // Lesson 26: End trace capture on error
@@ -850,6 +897,9 @@ export class ProductionAgent {
             : 0.8;
         let reflectionAttempt = 0;
         let lastResponse = '';
+        let incompleteActionRetries = 0;
+        const requestedArtifact = this.extractRequestedArtifact(task);
+        const executedToolNames = new Set();
         // Outer loop for reflection (if enabled)
         while (reflectionAttempt < maxReflectionAttempts) {
             reflectionAttempt++;
@@ -863,6 +913,9 @@ export class ProductionAgent {
                 });
                 // =======================================================================
                 // CANCELLATION CHECK
+                // Checks internal cancellation (ESC key) — always immediate.
+                // External cancellation (parent timeout) is checked after economics
+                // to allow graceful wrapup when wrapup has been requested.
                 // =======================================================================
                 if (this.cancellation?.isCancelled) {
                     this.cancellation.token.throwIfCancellationRequested();
@@ -916,6 +969,7 @@ export class ProductionAgent {
                                 attempt: 1,
                                 maxAttempts: 1,
                             });
+                            this.state.metrics.retryCount = (this.state.metrics.retryCount ?? 0) + 1;
                             // Mark that we've attempted recovery to prevent infinite loops
                             this.state._recoveryAttempted = true;
                             const tokensBefore = this.estimateContextTokens(messages);
@@ -1009,6 +1063,26 @@ export class ProductionAgent {
                     }
                 }
                 // =======================================================================
+                // GRACEFUL WRAPUP CHECK
+                // If a wrapup has been requested (e.g., timeout approaching), convert
+                // to forceTextOnly + inject wrapup prompt for structured summary.
+                // Must come after economics check (which may also set forceTextOnly).
+                // =======================================================================
+                if (this.wrapupRequested && !forceTextOnly) {
+                    forceTextOnly = true;
+                    budgetInjectedPrompt = TIMEOUT_WRAPUP_PROMPT;
+                    this.wrapupRequested = false;
+                }
+                // =======================================================================
+                // EXTERNAL CANCELLATION CHECK (deferred from above)
+                // Checked after wrapup so that graceful wrapup can intercept the timeout.
+                // If wrapup was already requested and converted to forceTextOnly above,
+                // we skip throwing here to allow one more text-only turn for the summary.
+                // =======================================================================
+                if (this.externalCancellationToken?.isCancellationRequested && !forceTextOnly) {
+                    this.externalCancellationToken.throwIfCancellationRequested();
+                }
+                // =======================================================================
                 // INTELLIGENT LOOP DETECTION & NUDGE INJECTION
                 // Uses economics system for doom loops, exploration saturation, etc.
                 // =======================================================================
@@ -1107,6 +1181,40 @@ export class ProductionAgent {
                 const MAX_CONTINUATIONS = resilienceConfig.maxContinuations ?? 3;
                 const AUTO_CONTINUE = resilienceConfig.autoContinue ?? true;
                 const MIN_CONTENT_LENGTH = resilienceConfig.minContentLength ?? 1;
+                const INCOMPLETE_ACTION_RECOVERY = resilienceConfig.incompleteActionRecovery ?? true;
+                const MAX_INCOMPLETE_ACTION_RETRIES = resilienceConfig.maxIncompleteActionRetries ?? 2;
+                const ENFORCE_REQUESTED_ARTIFACTS = resilienceConfig.enforceRequestedArtifacts ?? true;
+                // =================================================================
+                // PRE-FLIGHT BUDGET CHECK: Estimate if LLM call would exceed budget
+                // Catches cases where we're at e.g. 120k and next call adds ~35k
+                // =================================================================
+                if (this.economics && !forceTextOnly) {
+                    const estimatedInputTokens = this.estimateContextTokens(messages);
+                    const estimatedOutputTokens = 4096; // Conservative output estimate
+                    const currentUsage = this.economics.getUsage();
+                    const budget = this.economics.getBudget();
+                    const projectedTotal = currentUsage.tokens + estimatedInputTokens + estimatedOutputTokens;
+                    if (projectedTotal > budget.maxTokens) {
+                        this.observability?.logger?.warn('Pre-flight budget check: projected overshoot', {
+                            currentTokens: currentUsage.tokens,
+                            estimatedInput: estimatedInputTokens,
+                            projectedTotal,
+                            maxTokens: budget.maxTokens,
+                        });
+                        // Inject wrap-up prompt if not already injected
+                        if (!budgetInjectedPrompt) {
+                            messages.push({
+                                role: 'user',
+                                content: '[System] BUDGET CRITICAL: This is your LAST response. Summarize findings concisely and stop. Do NOT call tools.',
+                            });
+                            this.state.messages.push({
+                                role: 'user',
+                                content: '[System] BUDGET CRITICAL: This is your LAST response. Summarize findings concisely and stop. Do NOT call tools.',
+                            });
+                        }
+                        forceTextOnly = true;
+                    }
+                }
                 let response = await this.callLLM(messages);
                 let emptyRetries = 0;
                 let continuations = 0;
@@ -1136,6 +1244,7 @@ export class ProductionAgent {
                         attempt: emptyRetries,
                         maxAttempts: MAX_EMPTY_RETRIES,
                     });
+                    this.state.metrics.retryCount = (this.state.metrics.retryCount ?? 0) + 1;
                     this.observability?.logger?.warn('Empty LLM response, retrying', {
                         attempt: emptyRetries,
                         maxAttempts: MAX_EMPTY_RETRIES,
@@ -1193,10 +1302,51 @@ export class ProductionAgent {
                         });
                     }
                 }
+                // Phase 2b: Handle truncated tool calls (stopReason=max_tokens with tool calls present)
+                // When a model hits max_tokens mid-tool-call, the JSON arguments are truncated and unparseable.
+                // Instead of executing broken tool calls, strip them and ask the LLM to retry smaller.
+                if (resilienceEnabled && response.stopReason === 'max_tokens' && response.toolCalls?.length) {
+                    this.emit({
+                        type: 'resilience.truncated_tool_call',
+                        toolNames: response.toolCalls.map(tc => tc.name),
+                    });
+                    this.observability?.logger?.warn('Tool call truncated at max_tokens', {
+                        toolNames: response.toolCalls.map(tc => tc.name),
+                        outputTokens: response.usage?.outputTokens,
+                    });
+                    // Strip truncated tool calls, inject recovery message
+                    const truncatedResponse = response;
+                    response = { ...response, toolCalls: undefined };
+                    const recoveryMessage = {
+                        role: 'user',
+                        content: '[System: Your previous tool call was truncated because the output exceeded the token limit. ' +
+                            'The tool call arguments were cut off and could not be parsed. ' +
+                            'Please retry with a smaller approach: for write_file, break the content into smaller chunks ' +
+                            'or use edit_file for targeted changes instead of rewriting entire files.]',
+                    };
+                    messages.push({ role: 'assistant', content: truncatedResponse.content || '' });
+                    messages.push(recoveryMessage);
+                    this.state.messages.push({ role: 'assistant', content: truncatedResponse.content || '' });
+                    this.state.messages.push(recoveryMessage);
+                    response = await this.callLLM(messages);
+                }
                 // Record LLM usage for economics
                 if (this.economics && response.usage) {
                     this.economics.recordLLMUsage(response.usage.inputTokens, response.usage.outputTokens, this.config.model, response.usage.cost // Use actual cost from provider when available
                     );
+                    // =================================================================
+                    // POST-LLM BUDGET CHECK: Prevent tool execution if over budget
+                    // A single LLM call can push us over - catch it before running tools
+                    // =================================================================
+                    if (!forceTextOnly) {
+                        const postCheck = this.economics.checkBudget();
+                        if (!postCheck.canContinue) {
+                            this.observability?.logger?.warn('Budget exceeded after LLM call, skipping tool execution', {
+                                reason: postCheck.reason,
+                            });
+                            forceTextOnly = true;
+                        }
+                    }
                 }
                 // Add assistant message
                 const assistantMessage = {
@@ -1227,6 +1377,61 @@ export class ProductionAgent {
                             iteration: this.state.iteration,
                         });
                     }
+                    const incompleteAction = this.detectIncompleteActionResponse(response.content || '');
+                    const missingRequiredArtifact = ENFORCE_REQUESTED_ARTIFACTS
+                        ? this.isRequestedArtifactMissing(requestedArtifact, executedToolNames)
+                        : false;
+                    const shouldRecoverIncompleteAction = resilienceEnabled
+                        && INCOMPLETE_ACTION_RECOVERY
+                        && !forceTextOnly
+                        && (incompleteAction || missingRequiredArtifact);
+                    if (shouldRecoverIncompleteAction) {
+                        if (incompleteActionRetries < MAX_INCOMPLETE_ACTION_RETRIES) {
+                            incompleteActionRetries++;
+                            const reason = missingRequiredArtifact && requestedArtifact
+                                ? `missing_requested_artifact:${requestedArtifact}`
+                                : 'future_intent_without_action';
+                            this.emit({
+                                type: 'resilience.incomplete_action_detected',
+                                reason,
+                                attempt: incompleteActionRetries,
+                                maxAttempts: MAX_INCOMPLETE_ACTION_RETRIES,
+                                requiresArtifact: missingRequiredArtifact,
+                            });
+                            this.observability?.logger?.warn('Incomplete action detected, retrying with nudge', {
+                                reason,
+                                attempt: incompleteActionRetries,
+                                maxAttempts: MAX_INCOMPLETE_ACTION_RETRIES,
+                            });
+                            const nudgeMessage = {
+                                role: 'user',
+                                content: missingRequiredArtifact && requestedArtifact
+                                    ? `[System: You said you would complete the next action, but no tool call was made. The task requires creating or updating "${requestedArtifact}". Execute the required tool now, or explicitly explain why it cannot be produced.]`
+                                    : '[System: You described a next action but did not execute it. If work remains, call the required tool now. If the task is complete, provide a final answer with no pending action language.]',
+                            };
+                            messages.push(nudgeMessage);
+                            this.state.messages.push(nudgeMessage);
+                            continue;
+                        }
+                        const failureReason = missingRequiredArtifact && requestedArtifact
+                            ? `incomplete_action_missing_artifact:${requestedArtifact}`
+                            : 'incomplete_action_unresolved';
+                        this.emit({
+                            type: 'resilience.incomplete_action_failed',
+                            reason: failureReason,
+                            attempts: incompleteActionRetries,
+                            maxAttempts: MAX_INCOMPLETE_ACTION_RETRIES,
+                        });
+                        throw new Error(`LLM failed to complete requested action after ${incompleteActionRetries} retries (${failureReason})`);
+                    }
+                    if (incompleteActionRetries > 0) {
+                        this.emit({
+                            type: 'resilience.incomplete_action_recovered',
+                            reason: 'incomplete_action',
+                            attempts: incompleteActionRetries,
+                        });
+                        incompleteActionRetries = 0;
+                    }
                     // No tool calls (or forced to ignore), agent is done - compact tool outputs to save context
                     // The model has "consumed" the tool outputs and produced a response,
                     // so we can replace verbose outputs with compact summaries
@@ -1267,6 +1472,7 @@ export class ProductionAgent {
                 for (let i = 0; i < toolCalls.length; i++) {
                     const toolCall = toolCalls[i];
                     const result = toolResults[i];
+                    executedToolNames.add(toolCall.name);
                     this.economics?.recordToolCall(toolCall.name, toolCall.arguments, result?.result);
                 }
                 // Add tool results to messages (with truncation and proactive budget management)
@@ -1314,8 +1520,11 @@ export class ProductionAgent {
                         this.compactToolOutputs();
                     }
                 }
+                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);
+                    const sourceToolName = toolCallNameById.get(result.callId);
+                    const isExpensiveResult = sourceToolName === 'spawn_agent' || sourceToolName === 'spawn_agents_parallel';
                     // Truncate long outputs to save context
                     if (content.length > MAX_TOOL_OUTPUT_CHARS) {
                         content = content.slice(0, MAX_TOOL_OUTPUT_CHARS) + `\n\n... [truncated ${content.length - MAX_TOOL_OUTPUT_CHARS} chars]`;
@@ -1350,6 +1559,15 @@ export class ProductionAgent {
                         role: 'tool',
                         content,
                         toolCallId: result.callId,
+                        ...(isExpensiveResult
+                            ? {
+                                metadata: {
+                                    preserveFromCompaction: true,
+                                    costToRegenerate: 'high',
+                                    source: sourceToolName,
+                                },
+                            }
+                            : {}),
                     };
                     messages.push(toolMessage);
                     this.state.messages.push(toolMessage);
@@ -1715,6 +1933,19 @@ export class ProductionAgent {
             throw error;
         }
     }
+    /**
+     * Execute an async callback while excluding wall-clock wait time from duration budgeting.
+     * Used for external waits such as approval dialogs and delegation confirmation.
+     */
+    async withPausedDuration(fn) {
+        this.economics?.pauseDuration();
+        try {
+            return await fn();
+        }
+        finally {
+            this.economics?.resumeDuration();
+        }
+    }
     /**
      * Execute tool calls with safety checks and execution policy enforcement.
      */
@@ -1772,6 +2003,7 @@ export class ProductionAgent {
                 // =====================================================================
                 // EXECUTION POLICY ENFORCEMENT (Lesson 23)
                 // =====================================================================
+                let policyApprovedByUser = false;
                 if (this.executionPolicy) {
                     const policyContext = {
                         messages: this.state.messages,
@@ -1819,11 +2051,13 @@ export class ProductionAgent {
                     // Handle prompt policy - requires approval
                     if (evaluation.policy === 'prompt' && evaluation.requiresApproval) {
                         // Try to get approval through safety manager's human-in-loop
-                        if (this.safety?.humanInLoop) {
-                            const approval = await this.safety.humanInLoop.requestApproval(toolCall, `Policy requires approval: ${evaluation.reason}`);
+                        const humanInLoop = this.safety?.humanInLoop;
+                        if (humanInLoop) {
+                            const approval = await this.withPausedDuration(() => humanInLoop.requestApproval(toolCall, `Policy requires approval: ${evaluation.reason}`));
                             if (!approval.approved) {
                                 throw new Error(`Denied by user: ${approval.reason || 'No reason provided'}`);
                             }
+                            policyApprovedByUser = true;
                             // Create a grant for future similar calls if approved
                             this.executionPolicy.createGrant({
                                 toolName: toolCall.name,
@@ -1851,7 +2085,8 @@ export class ProductionAgent {
                 // SAFETY VALIDATION (Lesson 20-21)
                 // =====================================================================
                 if (this.safety) {
-                    const validation = await this.safety.validateAndApprove(toolCall, `Executing tool: ${toolCall.name}`);
+                    const safety = this.safety;
+                    const validation = await this.withPausedDuration(() => safety.validateAndApprove(toolCall, `Executing tool: ${toolCall.name}`, { skipHumanApproval: policyApprovedByUser }));
                     if (!validation.allowed) {
                         throw new Error(`Tool call blocked: ${validation.reason}`);
                     }
@@ -1900,17 +2135,21 @@ export class ProductionAgent {
                 // Execute tool (with sandbox if available)
                 let result;
                 if (this.safety?.sandbox) {
-                    // CRITICAL: spawn_agent needs a MUCH longer timeout than regular tools
+                    // CRITICAL: spawn_agent and spawn_agents_parallel need MUCH longer timeouts
                     // The default 60s sandbox timeout would kill subagents prematurely
                     // Subagents may run for minutes (per their own timeout config)
                     const isSpawnAgent = toolCall.name === 'spawn_agent';
+                    const isSpawnParallel = toolCall.name === 'spawn_agents_parallel';
+                    const isSubagentTool = isSpawnAgent || isSpawnParallel;
                     const subagentConfig = this.config.subagent;
                     const hasSubagentConfig = subagentConfig !== false && subagentConfig !== undefined;
                     const subagentTimeout = hasSubagentConfig
                         ? subagentConfig.defaultTimeout ?? 600000 // 10 min default
                         : 600000;
-                    // Use subagent timeout + buffer for spawn_agent, default for others
-                    const toolTimeout = isSpawnAgent ? subagentTimeout + 30000 : undefined;
+                    // Use subagent timeout + buffer for spawn tools, default for others
+                    // For spawn_agents_parallel, multiply by number of agents (they run in parallel,
+                    // but the total wall-clock time should still allow the slowest agent to complete)
+                    const toolTimeout = isSubagentTool ? subagentTimeout + 30000 : undefined;
                     result = await this.safety.sandbox.executeWithLimits(() => tool.execute(toolCall.arguments), toolTimeout);
                 }
                 else {
@@ -2256,7 +2495,14 @@ export class ProductionAgent {
      */
     getMetrics() {
         if (this.observability?.metrics) {
-            return this.observability.metrics.getMetrics();
+            const observed = this.observability.metrics.getMetrics();
+            return {
+                ...observed,
+                successCount: this.state.metrics.successCount ?? 0,
+                failureCount: this.state.metrics.failureCount ?? 0,
+                cancelCount: this.state.metrics.cancelCount ?? 0,
+                retryCount: this.state.metrics.retryCount ?? 0,
+            };
         }
         return this.state.metrics;
     }
@@ -2294,6 +2540,13 @@ export class ProductionAgent {
     getTraceCollector() {
         return this.traceCollector;
     }
+    /**
+     * Set a trace collector for this agent.
+     * Used for subagents to share the parent's trace collector (with subagent context).
+     */
+    setTraceCollector(collector) {
+        this.traceCollector = collector;
+    }
     /**
      * Get the learning store for cross-session learning.
      * Returns null if learning store is not enabled.
@@ -2381,6 +2634,10 @@ export class ProductionAgent {
                 llmCalls: 0,
                 toolCalls: 0,
                 duration: 0,
+                successCount: 0,
+                failureCount: 0,
+                cancelCount: 0,
+                retryCount: 0,
             },
             iteration: 0,
         };
@@ -2526,6 +2783,10 @@ export class ProductionAgent {
                 toolCalls: sanitized.metrics.toolCalls ?? 0,
                 duration: sanitized.metrics.duration ?? 0,
                 reflectionAttempts: sanitized.metrics.reflectionAttempts,
+                successCount: sanitized.metrics.successCount ?? 0,
+                failureCount: sanitized.metrics.failureCount ?? 0,
+                cancelCount: sanitized.metrics.cancelCount ?? 0,
+                retryCount: sanitized.metrics.retryCount ?? 0,
             };
         }
         // Restore plan if present
@@ -2573,10 +2834,20 @@ export class ProductionAgent {
      */
     compactToolOutputs() {
         const COMPACT_PREVIEW_LENGTH = 200; // Keep first 200 chars as preview
+        const MAX_PRESERVED_EXPENSIVE_RESULTS = 6;
         let compactedCount = 0;
         let savedChars = 0;
-        for (const msg of this.state.messages) {
+        const preservedExpensiveIndexes = this.state.messages
+            .map((msg, index) => ({ msg, index }))
+            .filter(({ msg }) => msg.role === 'tool' && msg.metadata?.preserveFromCompaction === true)
+            .map(({ index }) => index);
+        const preserveSet = new Set(preservedExpensiveIndexes.slice(-MAX_PRESERVED_EXPENSIVE_RESULTS));
+        for (let i = 0; i < this.state.messages.length; i++) {
+            const msg = this.state.messages[i];
             if (msg.role === 'tool' && msg.content && msg.content.length > COMPACT_PREVIEW_LENGTH * 2) {
+                if (msg.metadata?.preserveFromCompaction === true && preserveSet.has(i)) {
+                    continue;
+                }
                 const originalLength = msg.content.length;
                 const preview = msg.content.slice(0, COMPACT_PREVIEW_LENGTH).replace(/\n/g, ' ');
                 msg.content = `[${preview}...] (${originalLength} chars, compacted)`;
@@ -2608,6 +2879,42 @@ export class ProductionAgent {
         }
         return Math.ceil(totalChars / 4); // ~4 chars per token
     }
+    /**
+     * Extract a requested markdown artifact filename from a task prompt.
+     * Returns null when no explicit artifact requirement is detected.
+     */
+    extractRequestedArtifact(task) {
+        const markdownArtifactMatch = task.match(/(?:write|save|create)[^.\n]{0,120}\b([A-Za-z0-9._/-]+\.md)\b/i);
+        return markdownArtifactMatch?.[1] ?? null;
+    }
+    /**
+     * Check whether a requested artifact appears to be missing based on executed tools.
+     */
+    isRequestedArtifactMissing(requestedArtifact, executedToolNames) {
+        if (!requestedArtifact) {
+            return false;
+        }
+        const artifactWriteTools = ['write_file', 'edit_file', 'apply_patch', 'append_file'];
+        return !artifactWriteTools.some(toolName => executedToolNames.has(toolName));
+    }
+    /**
+     * Detect "future-intent" responses that imply the model has not completed work.
+     */
+    detectIncompleteActionResponse(content) {
+        const trimmed = content.trim();
+        if (!trimmed) {
+            return false;
+        }
+        const lower = trimmed.toLowerCase();
+        const futureIntentPatterns = [
+            /^(now|next|then)\s+(i\s+will|i'll|let me)\b/,
+            /^i\s+(will|am going to|can)\b/,
+            /^(let me|i'll|i will)\s+(create|write|save|do|make|generate|start)\b/,
+            /^(now|next|then)\s+i(?:'ll| will)\b/,
+        ];
+        const completionSignals = /\b(done|completed|finished|here is|created|saved|wrote)\b/;
+        return futureIntentPatterns.some(pattern => pattern.test(lower)) && !completionSignals.test(lower);
+    }
     /**
      * Get audit log (if human-in-loop is enabled).
      */
@@ -2630,8 +2937,8 @@ export class ProductionAgent {
         for (const role of roles) {
             this.multiAgent.registerRole(role);
         }
-        // Set up event forwarding
-        this.multiAgent.on(event => {
+        // Set up event forwarding (unsubscribe after operation to prevent memory leaks)
+        const unsubMultiAgent = this.multiAgent.on(event => {
             switch (event.type) {
                 case 'agent.spawn':
                     this.emit({ type: 'multiagent.spawn', agentId: event.agentId, role: event.role });
@@ -2647,14 +2954,19 @@ export class ProductionAgent {
                     break;
             }
         });
-        const result = await this.multiAgent.runWithTeam(task, {
-            roles,
-            consensusStrategy: this.config.multiAgent && isFeatureEnabled(this.config.multiAgent)
-                ? this.config.multiAgent.consensusStrategy || 'voting'
-                : 'voting',
-            communicationMode: 'broadcast',
-        });
-        return result;
+        try {
+            const result = await this.multiAgent.runWithTeam(task, {
+                roles,
+                consensusStrategy: this.config.multiAgent && isFeatureEnabled(this.config.multiAgent)
+                    ? this.config.multiAgent.consensusStrategy || 'voting'
+                    : 'voting',
+                communicationMode: 'broadcast',
+            });
+            return result;
+        }
+        finally {
+            unsubMultiAgent();
+        }
     }
     /**
      * Add a role to the multi-agent manager.
@@ -2677,8 +2989,8 @@ export class ProductionAgent {
             throw new Error('ReAct not enabled. Enable it in config to use runWithReAct()');
         }
         this.observability?.logger?.info('Running with ReAct', { task });
-        // Set up event forwarding
-        this.react.on(event => {
+        // Set up event forwarding (unsubscribe after operation to prevent memory leaks)
+        const unsubReact = this.react.on(event => {
             switch (event.type) {
                 case 'react.thought':
                     this.emit({ type: 'react.thought', step: event.step, thought: event.thought });
@@ -2694,15 +3006,20 @@ export class ProductionAgent {
                     break;
             }
         });
-        const trace = await this.react.run(task);
-        // Store trace in memory if available
-        if (this.memory && trace.finalAnswer) {
-            this.memory.storeConversation([
-                { role: 'user', content: task },
-                { role: 'assistant', content: trace.finalAnswer },
-            ]);
+        try {
+            const trace = await this.react.run(task);
+            // Store trace in memory if available
+            if (this.memory && trace.finalAnswer) {
+                this.memory.storeConversation([
+                    { role: 'user', content: task },
+                    { role: 'assistant', content: trace.finalAnswer },
+                ]);
+            }
+            return trace;
+        }
+        finally {
+            unsubReact();
         }
-        return trace;
     }
     /**
      * Get the ReAct trace formatted as a string.
@@ -2813,6 +3130,11 @@ export class ProductionAgent {
         if (!this.threadManager) {
             throw new Error('Thread management not enabled. Enable it in config to use createCheckpoint()');
         }
+        // CRITICAL: Sync current state.messages to threadManager before checkpoint
+        // The run() method adds messages directly to this.state.messages but doesn't sync
+        // to threadManager, so thread.messages would be empty without this sync
+        const thread = this.threadManager.getActiveThread();
+        thread.messages = [...this.state.messages];
         const checkpoint = this.threadManager.createCheckpoint({
             label,
             agentState: this.state,
@@ -2987,8 +3309,12 @@ export class ProductionAgent {
     /**
      * Spawn an agent to execute a task.
      * Returns the result when the agent completes.
+     *
+     * @param agentName - Name of the agent to spawn (researcher, coder, etc.)
+     * @param task - The task description for the agent
+     * @param constraints - Optional constraints to keep the subagent focused
      */
-    async spawnAgent(agentName, task) {
+    async spawnAgent(agentName, task, constraints) {
         if (!this.agentRegistry) {
             return {
                 success: false,
@@ -3004,10 +3330,10 @@ export class ProductionAgent {
                 metrics: { tokens: 0, duration: 0, toolCalls: 0 },
             };
         }
-        // DUPLICATE SPAWN PREVENTION
-        // Create a key from agent name and normalized task (first 150 chars to catch same intent)
+        // DUPLICATE SPAWN PREVENTION with SEMANTIC SIMILARITY
+        // First try exact string match, then check semantic similarity for similar tasks
+        const SEMANTIC_SIMILARITY_THRESHOLD = 0.75; // 75% similarity = duplicate
         const taskKey = `${agentName}:${task.slice(0, 150).toLowerCase().replace(/\s+/g, ' ').trim()}`;
-        const existing = this.spawnedTasks.get(taskKey);
         const now = Date.now();
         // Clean up old entries (older than dedup window)
         for (const [key, entry] of this.spawnedTasks.entries()) {
@@ -3015,32 +3341,63 @@ export class ProductionAgent {
                 this.spawnedTasks.delete(key);
             }
         }
-        if (existing && now - existing.timestamp < ProductionAgent.SPAWN_DEDUP_WINDOW_MS) {
-            // Same task spawned within the dedup window - return cached result
-            // Log this as a warning for observability (no special event type needed)
+        // Check for exact match first
+        let existingMatch = this.spawnedTasks.get(taskKey);
+        let matchType = 'exact';
+        // If no exact match, check for semantic similarity among same agent's tasks
+        if (!existingMatch) {
+            for (const [key, entry] of this.spawnedTasks.entries()) {
+                // Only compare tasks from the same agent type
+                if (!key.startsWith(`${agentName}:`))
+                    continue;
+                if (now - entry.timestamp >= ProductionAgent.SPAWN_DEDUP_WINDOW_MS)
+                    continue;
+                // Extract the task portion from the key
+                const existingTask = key.slice(agentName.length + 1);
+                const similarity = calculateTaskSimilarity(task, existingTask);
+                if (similarity >= SEMANTIC_SIMILARITY_THRESHOLD) {
+                    existingMatch = entry;
+                    matchType = 'semantic';
+                    this.observability?.logger?.debug('Semantic duplicate detected', {
+                        agent: agentName,
+                        newTask: task.slice(0, 80),
+                        existingTask: existingTask.slice(0, 80),
+                        similarity: (similarity * 100).toFixed(1) + '%',
+                    });
+                    break;
+                }
+            }
+        }
+        if (existingMatch && now - existingMatch.timestamp < ProductionAgent.SPAWN_DEDUP_WINDOW_MS) {
+            // Same or semantically similar task spawned within the dedup window
             this.observability?.logger?.warn('Duplicate spawn prevented', {
                 agent: agentName,
                 task: task.slice(0, 100),
-                originalTimestamp: existing.timestamp,
-                elapsedMs: now - existing.timestamp,
+                matchType,
+                originalTimestamp: existingMatch.timestamp,
+                elapsedMs: now - existingMatch.timestamp,
             });
-            const duplicateMessage = `[DUPLICATE SPAWN PREVENTED]\n` +
-                `This task was already spawned ${Math.round((now - existing.timestamp) / 1000)}s ago.\n` +
-                `${existing.queuedChanges > 0
-                    ? `The previous spawn queued ${existing.queuedChanges} change(s) to the pending plan.\n` +
+            const duplicateMessage = `[DUPLICATE SPAWN PREVENTED${matchType === 'semantic' ? ' - SEMANTIC MATCH' : ''}]\n` +
+                `This task was already spawned ${Math.round((now - existingMatch.timestamp) / 1000)}s ago.\n` +
+                `${existingMatch.queuedChanges > 0
+                    ? `The previous spawn queued ${existingMatch.queuedChanges} change(s) to the pending plan.\n` +
                         `These changes are already in your plan - do NOT spawn again.\n`
-                    : ''}Previous result summary:\n${existing.result.slice(0, 500)}`;
+                    : ''}Previous result summary:\n${existingMatch.result.slice(0, 500)}`;
             return {
                 success: true, // Mark as success since original task completed
                 output: duplicateMessage,
                 metrics: { tokens: 0, duration: 0, toolCalls: 0 },
             };
         }
-        this.emit({ type: 'agent.spawn', agentId: `spawn-${Date.now()}`, name: agentName, task });
+        // Generate a unique ID for this agent instance that will be used consistently
+        // throughout the agent's lifecycle (spawn event, token events, completion events)
+        const agentId = `spawn-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        this.emit({ type: 'agent.spawn', agentId, name: agentName, task });
         this.observability?.logger?.info('Spawning agent', { name: agentName, task });
         const startTime = Date.now();
         const childSessionId = `subagent-${agentName}-${Date.now()}`;
         const childTraceId = `trace-${childSessionId}`;
+        let workerResultId;
         try {
             // Filter tools for this agent
             const agentTools = filterToolsForAgent(agentDef, Array.from(this.tools.values()));
@@ -3049,17 +3406,108 @@ export class ProductionAgent {
             const resolvedModel = (agentDef.model && agentDef.model.includes('/'))
                 ? agentDef.model
                 : this.config.model;
-            // Get subagent config with defaults
-            // Note: subagent config is SubagentConfig | false from buildConfig
+            // Persist subagent task lifecycle in durable storage when available
+            if (this.store?.hasWorkerResultsFeature()) {
+                try {
+                    workerResultId = this.store.createWorkerResult(agentId, task.slice(0, 500), resolvedModel || 'default');
+                }
+                catch (storeErr) {
+                    this.observability?.logger?.warn('Failed to create worker result record', {
+                        agentId,
+                        error: storeErr.message,
+                    });
+                }
+            }
+            // Get subagent config with agent-type-specific timeouts and iteration limits
+            // Uses dynamic configuration based on agent type (researcher needs more time than reviewer)
             const subagentConfig = this.config.subagent;
             const hasSubagentConfig = subagentConfig !== false && subagentConfig !== undefined;
-            const defaultMaxIterations = hasSubagentConfig
-                ? subagentConfig.defaultMaxIterations ?? 25
-                : 25; // Increased from 10 to allow more thorough exploration
-            const subagentTimeout = hasSubagentConfig
-                ? subagentConfig.defaultTimeout ?? 600000
-                : 600000; // Increased from 120s to 600s (10 minutes) for deeper analysis
+            // Agent-type-specific timeout: researchers get 5min, reviewers get 2min, etc.
+            const agentTypeTimeout = getSubagentTimeout(agentName);
+            const configTimeout = hasSubagentConfig
+                ? subagentConfig.defaultTimeout
+                : undefined;
+            const subagentTimeout = configTimeout ?? agentTypeTimeout;
+            // Agent-type-specific iteration limit: researchers get 25, documenters get 10, etc.
+            const agentTypeMaxIter = getSubagentMaxIterations(agentName);
+            const configMaxIter = hasSubagentConfig
+                ? subagentConfig.defaultMaxIterations
+                : undefined;
+            const defaultMaxIterations = agentDef.maxIterations ?? configMaxIter ?? agentTypeMaxIter;
+            // BLACKBOARD CONTEXT INJECTION
+            // Gather relevant context from the blackboard for the subagent
+            let blackboardContext = '';
+            const parentAgentId = `parent-${Date.now()}`;
+            if (this.blackboard) {
+                // Post parent's exploration context before spawning
+                this.blackboard.post(parentAgentId, {
+                    topic: 'spawn.parent_context',
+                    content: `Parent spawning ${agentName} for task: ${task.slice(0, 200)}`,
+                    type: 'progress',
+                    confidence: 1,
+                    metadata: { agentName, taskPreview: task.slice(0, 100) },
+                });
+                // Gather recent findings that might help the subagent
+                const recentFindings = this.blackboard.query({
+                    limit: 5,
+                    types: ['discovery', 'analysis', 'progress'],
+                    minConfidence: 0.7,
+                });
+                if (recentFindings.length > 0) {
+                    const findingsSummary = recentFindings
+                        .map(f => `- [${f.agentId}] ${f.topic}: ${f.content.slice(0, 150)}${f.content.length > 150 ? '...' : ''}`)
+                        .join('\n');
+                    blackboardContext = `\n\n**BLACKBOARD CONTEXT (from parent/sibling agents):**\n${findingsSummary}\n`;
+                }
+            }
+            // Check for files already being modified in parent's pending plan
+            const currentPlan = this.pendingPlanManager.getPendingPlan();
+            if (currentPlan && currentPlan.proposedChanges.length > 0) {
+                const pendingFiles = currentPlan.proposedChanges
+                    .filter((c) => c.tool === 'write_file' || c.tool === 'edit_file')
+                    .map((c) => c.args.path || c.args.file_path)
+                    .filter(Boolean);
+                if (pendingFiles.length > 0) {
+                    blackboardContext += `\n**FILES ALREADY IN PENDING PLAN (do not duplicate):**\n${pendingFiles.slice(0, 10).join('\n')}\n`;
+                }
+            }
+            // CONSTRAINT INJECTION
+            // Add constraints to the subagent's context if provided
+            // Also always include budget awareness so subagents know their limits
+            const constraintParts = [];
+            // BUDGET AWARENESS: Always inject so subagent understands its limits
+            const subagentBudgetTokens = constraints?.maxTokens ?? SUBAGENT_BUDGET.maxTokens ?? 100000;
+            const subagentBudgetMinutes = Math.round((SUBAGENT_BUDGET.maxDuration ?? 240000) / 60000);
+            constraintParts.push(`**RESOURCE AWARENESS (CRITICAL):**\n` +
+                `- Token budget: ~${(subagentBudgetTokens / 1000).toFixed(0)}k tokens\n` +
+                `- Time limit: ~${subagentBudgetMinutes} minutes\n` +
+                `- You will receive warnings at 70% usage. When warned, WRAP UP immediately.\n` +
+                `- Do not explore indefinitely - be focused and efficient.\n` +
+                `- If approaching limits, summarize findings and return.\n` +
+                `- **STRUCTURED WRAPUP:** When told to wrap up, respond with ONLY this JSON (no tool calls):\n` +
+                `  {"findings":[...], "actionsTaken":[...], "failures":[...], "remainingWork":[...], "suggestedNextSteps":[...]}`);
+            if (constraints) {
+                if (constraints.focusAreas && constraints.focusAreas.length > 0) {
+                    constraintParts.push(`**FOCUS AREAS (limit exploration to these paths):**\n${constraints.focusAreas.map(a => `  - ${a}`).join('\n')}`);
+                }
+                if (constraints.excludeAreas && constraints.excludeAreas.length > 0) {
+                    constraintParts.push(`**EXCLUDED AREAS (do NOT explore these):**\n${constraints.excludeAreas.map(a => `  - ${a}`).join('\n')}`);
+                }
+                if (constraints.requiredDeliverables && constraints.requiredDeliverables.length > 0) {
+                    constraintParts.push(`**REQUIRED DELIVERABLES (you must produce these):**\n${constraints.requiredDeliverables.map(d => `  - ${d}`).join('\n')}`);
+                }
+                if (constraints.timeboxMinutes) {
+                    constraintParts.push(`**TIME LIMIT:** ${constraints.timeboxMinutes} minutes (soft limit - wrap up if approaching)`);
+                }
+            }
+            const constraintContext = `\n\n**EXECUTION CONSTRAINTS:**\n${constraintParts.join('\n\n')}\n`;
+            // Build subagent system prompt with subagent-specific plan mode addition
+            const parentMode = this.getMode();
+            const subagentSystemPrompt = parentMode === 'plan'
+                ? `${agentDef.systemPrompt}\n\n${SUBAGENT_PLAN_MODE_ADDITION}${blackboardContext}${constraintContext}`
+                : `${agentDef.systemPrompt}${blackboardContext}${constraintContext}`;
             // Create a sub-agent with the agent's config
+            // Use SUBAGENT_BUDGET to constrain resource usage (prevents runaway token consumption)
             const subAgent = new ProductionAgent({
                 provider: this.provider,
                 tools: agentTools,
@@ -3067,7 +3515,7 @@ export class ProductionAgent {
                 toolResolver: this.toolResolver || undefined,
                 // Pass MCP tool summaries so subagent knows what tools are available
                 mcpToolSummaries: this.config.mcpToolSummaries,
-                systemPrompt: agentDef.systemPrompt,
+                systemPrompt: subagentSystemPrompt,
                 model: resolvedModel,
                 maxIterations: agentDef.maxIterations || defaultMaxIterations,
                 // Inherit some features but keep subagent simpler
@@ -3087,32 +3535,89 @@ export class ProductionAgent {
                 },
                 // Share parent's blackboard for coordination between parallel subagents
                 blackboard: this.blackboard || undefined,
+                // CONSTRAINED BUDGET: Subagents get smaller budget to prevent runaway consumption
+                // Uses SUBAGENT_BUDGET (100k tokens, 4 min) vs STANDARD_BUDGET (200k, 5 min)
+                budget: constraints?.maxTokens
+                    ? { ...SUBAGENT_BUDGET, maxTokens: constraints.maxTokens }
+                    : SUBAGENT_BUDGET,
             });
             // CRITICAL: Subagent inherits parent's mode
             // This ensures that if parent is in plan mode:
             // - Subagent's read operations execute immediately (visible exploration)
             // - Subagent's write operations get queued in the subagent's pending plan
             // - User maintains control over what actually gets written
-            const parentMode = this.getMode();
             if (parentMode !== 'build') {
                 subAgent.setMode(parentMode);
             }
             // Pass parent's iteration count to subagent for accurate budget tracking
             // This prevents subagents from consuming excessive iterations when parent already used many
             subAgent.setParentIterations(this.getTotalIterations());
-            // Forward events from subagent with context
-            subAgent.subscribe(event => {
-                // Tag event with subagent source so TUI can display it properly
-                const taggedEvent = { ...event, subagent: agentName };
+            // UNIFIED TRACING: Share parent's trace collector with subagent context
+            // This ensures all subagent events are written to the same trace file as the parent,
+            // tagged with subagent context for proper aggregation in /trace output
+            if (this.traceCollector) {
+                const subagentTraceView = this.traceCollector.createSubagentView({
+                    parentSessionId: this.traceCollector.getSessionId() || 'unknown',
+                    agentType: agentName,
+                    spawnedAtIteration: this.state.iteration,
+                });
+                subAgent.setTraceCollector(subagentTraceView);
+            }
+            // GRACEFUL TIMEOUT with WRAPUP PHASE
+            // Instead of instant death on timeout, the subagent gets a wrapup window
+            // to produce a structured summary before being killed:
+            // 1. Normal operation: progress extends idle timer
+            // 2. Wrapup phase: 30s before hard kill, wrapup callback fires → forceTextOnly
+            // 3. Hard kill: race() throws CancellationError after wrapup window
+            const IDLE_TIMEOUT = 120000; // 2 minutes without progress = timeout
+            let WRAPUP_WINDOW = 30000;
+            let IDLE_CHECK_INTERVAL = 5000;
+            if (this.config.subagent) {
+                WRAPUP_WINDOW = this.config.subagent.wrapupWindowMs ?? WRAPUP_WINDOW;
+                IDLE_CHECK_INTERVAL = this.config.subagent.idleCheckIntervalMs ?? IDLE_CHECK_INTERVAL;
+            }
+            const progressAwareTimeout = createGracefulTimeout(subagentTimeout, // Max total time (hard limit from agent type config)
+            IDLE_TIMEOUT, // Idle timeout (soft limit - no progress triggers this)
+            WRAPUP_WINDOW, // Wrapup window before hard kill
+            IDLE_CHECK_INTERVAL);
+            // Register wrapup callback — fires 30s before hard kill
+            // This triggers the subagent's forceTextOnly path for a structured summary
+            progressAwareTimeout.onWrapupWarning(() => {
+                this.emit({
+                    type: 'subagent.wrapup.started',
+                    agentId,
+                    agentType: agentName,
+                    reason: 'Timeout approaching - graceful wrapup window opened',
+                    elapsedMs: Date.now() - startTime,
+                });
+                subAgent.requestWrapup('Timeout approaching — produce structured summary');
+            });
+            // Forward events from subagent with context (track for cleanup)
+            // Also report progress to the timeout tracker
+            const unsubSubAgent = subAgent.subscribe(event => {
+                // Tag event with subagent source AND unique ID so TUI can properly attribute
+                // events to the specific agent instance (critical for multiple same-type agents)
+                const taggedEvent = { ...event, subagent: agentName, subagentId: agentId };
                 this.emit(taggedEvent);
+                // Report progress for timeout extension
+                // Progress events: tool calls, LLM responses, token updates
+                const progressEvents = ['tool.start', 'tool.complete', 'llm.start', 'llm.complete'];
+                if (progressEvents.includes(event.type)) {
+                    progressAwareTimeout.reportProgress();
+                }
             });
-            // Create timeout token for subagent execution
-            const timeoutSource = createTimeoutToken(subagentTimeout);
-            // Link parent's cancellation with subagent timeout so ESC propagates to subagents
+            // Link parent's cancellation with progress-aware timeout so ESC propagates to subagents
             const parentSource = this.cancellation?.getSource();
             const effectiveSource = parentSource
-                ? createLinkedToken(parentSource, timeoutSource)
-                : timeoutSource;
+                ? createLinkedToken(parentSource, progressAwareTimeout)
+                : progressAwareTimeout;
+            // CRITICAL: Pass the cancellation token to the subagent so it can check and stop
+            // gracefully when timeout fires. Without this, the subagent continues running as
+            // a "zombie" even after race() returns with a timeout error.
+            subAgent.setExternalCancellation(effectiveSource.token);
+            // Pause parent's duration timer while subagent runs to prevent
+            // the parent from timing out on wall-clock while waiting for subagent
+            this.economics?.pauseDuration();
             try {
                 // Run the task with cancellation propagation from parent
                 const result = await race(subAgent.run(task), effectiveSource.token);
@@ -3165,6 +3670,8 @@ export class ProductionAgent {
                 const finalOutput = queuedChangeSummary
                     ? (result.response || '') + queuedChangeSummary
                     : (result.response || result.error || '');
+                // Parse structured closure report from agent's response (if it produced one)
+                const structured = parseStructuredClosureReport(result.response || '', 'completed');
                 const spawnResultFinal = {
                     success: result.success,
                     output: finalOutput,
@@ -3173,13 +3680,43 @@ export class ProductionAgent {
                         duration,
                         toolCalls: result.metrics.toolCalls,
                     },
+                    structured,
                 };
+                if (workerResultId && this.store?.hasWorkerResultsFeature()) {
+                    try {
+                        this.store.completeWorkerResult(workerResultId, {
+                            fullOutput: finalOutput,
+                            summary: finalOutput.slice(0, 500),
+                            artifacts: structured ? [{ type: 'structured_report', data: structured }] : undefined,
+                            metrics: {
+                                tokens: result.metrics.totalTokens,
+                                duration,
+                                toolCalls: result.metrics.toolCalls,
+                            },
+                        });
+                    }
+                    catch (storeErr) {
+                        this.observability?.logger?.warn('Failed to persist worker result', {
+                            agentId,
+                            error: storeErr.message,
+                        });
+                    }
+                }
                 this.emit({
                     type: 'agent.complete',
-                    agentId: agentName,
+                    agentId, // Use unique spawn ID for precise tracking
+                    agentType: agentName, // Keep type for display purposes
                     success: result.success,
                     output: finalOutput.slice(0, 500), // Include output preview
                 });
+                if (progressAwareTimeout.isInWrapupPhase()) {
+                    this.emit({
+                        type: 'subagent.wrapup.completed',
+                        agentId,
+                        agentType: agentName,
+                        elapsedMs: Date.now() - startTime,
+                    });
+                }
                 // Enhanced tracing: Record subagent completion
                 this.traceCollector?.record({
                     type: 'subagent.link',
@@ -3206,6 +3743,8 @@ export class ProductionAgent {
                         },
                     },
                 });
+                // Unsubscribe from subagent events before cleanup
+                unsubSubAgent();
                 await subAgent.cleanup();
                 // Cache result for duplicate spawn prevention
                 // Use the same taskKey from the dedup check above
@@ -3223,8 +3762,31 @@ export class ProductionAgent {
                     const isUserCancellation = parentSource?.isCancellationRequested;
                     const reason = isUserCancellation
                         ? 'User cancelled'
-                        : `Timed out after ${subagentTimeout}ms`;
-                    this.emit({ type: 'agent.error', agentId: agentName, error: reason });
+                        : err.reason || `Timed out after ${subagentTimeout}ms`;
+                    this.emit({ type: 'agent.error', agentId, agentType: agentName, error: reason });
+                    if (!isUserCancellation) {
+                        this.emit({
+                            type: 'subagent.timeout.hard_kill',
+                            agentId,
+                            agentType: agentName,
+                            reason,
+                            elapsedMs: Date.now() - startTime,
+                        });
+                    }
+                    // =======================================================================
+                    // PRESERVE PARTIAL RESULTS
+                    // Instead of discarding all work, capture whatever the subagent produced
+                    // before timeout. This prevents the "zombie agent" problem where tokens
+                    // are consumed but results are lost.
+                    // =======================================================================
+                    const subagentState = subAgent.getState();
+                    const subagentMetrics = subAgent.getMetrics();
+                    // Extract partial response from the last assistant message
+                    const assistantMessages = subagentState.messages.filter(m => m.role === 'assistant');
+                    const lastAssistantMsg = assistantMessages[assistantMessages.length - 1];
+                    const partialResponse = typeof lastAssistantMsg?.content === 'string'
+                        ? lastAssistantMsg.content
+                        : '';
                     // Extract pending plan before cleanup (even on cancellation, preserve any queued work)
                     let cancelledQueuedSummary = '';
                     if (subAgent.hasPendingPlan()) {
@@ -3260,33 +3822,99 @@ export class ProductionAgent {
                             this.pendingPlanManager.appendExplorationFinding(`[${agentName}] ${subPlan.explorationSummary}`);
                         }
                     }
-                    // Try to cleanup the subagent gracefully
+                    // Unsubscribe from subagent events and cleanup gracefully
+                    unsubSubAgent();
                     try {
                         await subAgent.cleanup();
                     }
                     catch {
                         // Ignore cleanup errors on cancellation
                     }
+                    // Build output message with partial results
                     const baseOutput = isUserCancellation
                         ? `Subagent '${agentName}' was cancelled by user.`
-                        : `Subagent '${agentName}' timed out after ${Math.round(subagentTimeout / 1000)}s. The task may be too complex or the model may be slow.`;
+                        : `Subagent '${agentName}' timed out after ${Math.round(subagentTimeout / 1000)}s.`;
+                    // Include partial response if we have one
+                    const partialResultSection = partialResponse
+                        ? `\n\n[PARTIAL RESULTS BEFORE TIMEOUT]\n${partialResponse.slice(0, 2000)}${partialResponse.length > 2000 ? '...(truncated)' : ''}`
+                        : '';
+                    // Enhanced tracing: Record subagent timeout with partial results
+                    this.traceCollector?.record({
+                        type: 'subagent.link',
+                        data: {
+                            parentSessionId: this.traceCollector.getSessionId() || 'unknown',
+                            childSessionId,
+                            childTraceId,
+                            childConfig: {
+                                agentType: agentName,
+                                model: resolvedModel || 'default',
+                                task,
+                                tools: agentTools.map(t => t.name),
+                            },
+                            spawnContext: {
+                                reason: `Delegated task: ${task.slice(0, 100)}`,
+                                expectedOutcome: agentDef.description,
+                                parentIteration: this.state.iteration,
+                            },
+                            result: {
+                                success: false,
+                                summary: `[TIMEOUT] ${baseOutput}\n${partialResponse.slice(0, 200)}`,
+                                tokensUsed: subagentMetrics.totalTokens,
+                                durationMs: duration,
+                            },
+                        },
+                    });
+                    // Parse structured closure report from partial response
+                    const exitReason = isUserCancellation ? 'cancelled' : 'timeout_graceful';
+                    const structured = parseStructuredClosureReport(partialResponse, exitReason, task);
+                    if (workerResultId && this.store?.hasWorkerResultsFeature()) {
+                        try {
+                            this.store.failWorkerResult(workerResultId, reason);
+                        }
+                        catch (storeErr) {
+                            this.observability?.logger?.warn('Failed to mark cancelled worker result as failed', {
+                                agentId,
+                                error: storeErr.message,
+                            });
+                        }
+                    }
                     return {
                         success: false,
-                        output: baseOutput + cancelledQueuedSummary,
-                        metrics: { tokens: 0, duration, toolCalls: 0 },
+                        output: baseOutput + partialResultSection + cancelledQueuedSummary,
+                        // IMPORTANT: Use actual metrics instead of zeros
+                        // This ensures accurate token tracking in /trace output
+                        metrics: {
+                            tokens: subagentMetrics.totalTokens,
+                            duration,
+                            toolCalls: subagentMetrics.toolCalls,
+                        },
+                        structured,
                     };
                 }
                 throw err; // Re-throw non-cancellation errors
             }
             finally {
+                // Resume parent's duration timer now that subagent is done
+                this.economics?.resumeDuration();
                 // Dispose both sources (linked source disposes its internal state, timeout source handles its timer)
                 effectiveSource.dispose();
-                timeoutSource.dispose();
+                progressAwareTimeout.dispose();
             }
         }
         catch (err) {
             const error = err instanceof Error ? err.message : String(err);
-            this.emit({ type: 'agent.error', agentId: agentName, error });
+            this.emit({ type: 'agent.error', agentId, agentType: agentName, error });
+            if (workerResultId && this.store?.hasWorkerResultsFeature()) {
+                try {
+                    this.store.failWorkerResult(workerResultId, error);
+                }
+                catch (storeErr) {
+                    this.observability?.logger?.warn('Failed to mark worker result as failed', {
+                        agentId,
+                        error: storeErr.message,
+                    });
+                }
+            }
             return {
                 success: false,
                 output: `Agent error: ${error}`,
@@ -3297,6 +3925,9 @@ export class ProductionAgent {
     /**
      * Spawn multiple agents in parallel to work on independent tasks.
      * Uses the shared blackboard for coordination and conflict prevention.
+     *
+     * Uses Promise.allSettled to handle partial failures gracefully - if one
+     * agent fails or times out, others can still complete successfully.
      */
     async spawnAgentsParallel(tasks) {
         // Emit start event for TUI visibility
@@ -3305,9 +3936,28 @@ export class ProductionAgent {
             count: tasks.length,
             agents: tasks.map(t => t.agent),
         });
-        // Execute all tasks in parallel
+        // Execute all tasks in parallel using allSettled to handle partial failures
         const promises = tasks.map(({ agent, task }) => this.spawnAgent(agent, task));
-        const results = await Promise.all(promises);
+        const settled = await Promise.allSettled(promises);
+        // Convert settled results to SpawnResult array
+        const results = settled.map((result, i) => {
+            if (result.status === 'fulfilled') {
+                return result.value;
+            }
+            // Handle rejected promises (shouldn't happen since spawnAgent catches errors internally,
+            // but this is a safety net for unexpected failures)
+            const error = result.reason instanceof Error ? result.reason.message : String(result.reason);
+            this.emit({
+                type: 'agent.error',
+                agentId: tasks[i].agent,
+                error: `Unexpected parallel spawn error: ${error}`,
+            });
+            return {
+                success: false,
+                output: `Parallel spawn error: ${error}`,
+                metrics: { tokens: 0, duration: 0, toolCalls: 0 },
+            };
+        });
         // Emit completion event
         this.emit({
             type: 'parallel.spawn.complete',
@@ -3456,7 +4106,7 @@ If the task is a simple question or doesn't need specialized handling, set bestA
             const topSuggestion = suggestions[0];
             // If confirmation callback provided, ask user
             if (confirmDelegate && topSuggestion) {
-                const confirmed = await confirmDelegate(topSuggestion.agent, topSuggestion.reason);
+                const confirmed = await this.withPausedDuration(() => confirmDelegate(topSuggestion.agent, topSuggestion.reason));
                 if (!confirmed) {
                     // User declined, run with main agent
                     return this.run(task);
@@ -3513,6 +4163,14 @@ If the task is a simple question or doesn't need specialized handling, set bestA
     getResourceStatus() {
         return this.resourceManager?.getStatusString() || null;
     }
+    /**
+     * Reset CPU time counter for the resource manager.
+     * Call this when starting a new prompt to allow per-prompt time limits
+     * instead of session-wide limits.
+     */
+    resetResourceTimer() {
+        this.resourceManager?.resetCpuTime();
+    }
     // =========================================================================
     // LSP (LANGUAGE SERVER) METHODS
     // =========================================================================
@@ -3663,6 +4321,37 @@ If the task is a simple question or doesn't need specialized handling, set bestA
     setParentIterations(count) {
         this.parentIterations = count;
     }
+    /**
+     * Set an external cancellation token for this agent.
+     * Used when spawning subagents to propagate parent timeout/cancellation.
+     * The agent will check this token in its main loop and stop gracefully
+     * when cancellation is requested, preserving partial results.
+     */
+    setExternalCancellation(token) {
+        this.externalCancellationToken = token;
+    }
+    /**
+     * Set a SQLite store instance for durable persistence features.
+     */
+    setStore(store) {
+        this.store = store;
+    }
+    /**
+     * Check if external cancellation has been requested.
+     * Returns true if the external token signals cancellation.
+     */
+    isExternallyCancelled() {
+        return this.externalCancellationToken?.isCancellationRequested ?? false;
+    }
+    /**
+     * Request a graceful wrapup of the agent's current work.
+     * On the next main loop iteration, the agent will produce a structured summary
+     * instead of making more tool calls.
+     */
+    requestWrapup(reason) {
+        this.wrapupRequested = true;
+        this.wrapupReason = reason || 'Timeout approaching';
+    }
     /**
      * Get total iterations (this agent + parent).
      * Used for accurate budget tracking across subagent hierarchies.
@@ -3844,6 +4533,12 @@ If the task is a simple question or doesn't need specialized handling, set bestA
     getAgentRegistry() {
         return this.agentRegistry;
     }
+    /**
+     * Get the task manager instance for task tracking.
+     */
+    getTaskManager() {
+        return this.taskManager;
+    }
     /**
      * Get all loaded skills.
      */
@@ -3930,6 +4625,29 @@ If the task is a simple question or doesn't need specialized handling, set bestA
      * Cleanup resources.
      */
     async cleanup() {
+        // Unsubscribe all event listeners (prevents memory leaks in long sessions)
+        for (const unsub of this.unsubscribers) {
+            try {
+                unsub();
+            }
+            catch {
+                // Ignore unsubscribe errors during cleanup
+            }
+        }
+        this.unsubscribers = [];
+        // Flush trace collector before cleanup
+        await this.traceCollector?.flush();
+        // Clear blackboard (releases file claim locks)
+        this.blackboard?.clear();
+        // Wait for any pending init before cleanup
+        if (this.initPromises.length > 0) {
+            try {
+                await Promise.all(this.initPromises);
+            }
+            catch {
+                // Ignore init errors during cleanup
+            }
+        }
         this.cancellation?.cleanup();
         this.resourceManager?.cleanup();
         await this.lspManager?.cleanup();
@@ -4137,4 +4855,64 @@ export class ProductionAgentBuilder {
 export function buildAgent() {
     return new ProductionAgentBuilder();
 }
+// =============================================================================
+// STRUCTURED CLOSURE REPORT PARSER
+// =============================================================================
+/**
+ * Parse a structured closure report from a subagent's text response.
+ * The subagent may have produced JSON in response to a TIMEOUT_WRAPUP_PROMPT.
+ *
+ * @param text - The subagent's last response text
+ * @param defaultExitReason - Exit reason to use (completed, timeout_graceful, cancelled, etc.)
+ * @param fallbackTask - Original task description for fallback remainingWork
+ * @returns Parsed StructuredClosureReport, or undefined if no JSON found and no fallback needed
+ */
+export function parseStructuredClosureReport(text, defaultExitReason, fallbackTask) {
+    if (!text) {
+        // No text at all — create a hard timeout fallback if we have a task
+        if (fallbackTask) {
+            return {
+                findings: [],
+                actionsTaken: [],
+                failures: ['Timeout before producing structured summary'],
+                remainingWork: [fallbackTask],
+                exitReason: 'timeout_hard',
+            };
+        }
+        return undefined;
+    }
+    try {
+        // Try to extract JSON from the response
+        const jsonMatch = text.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            const parsed = JSON.parse(jsonMatch[0]);
+            // Validate that it looks like a closure report (has at least one expected field)
+            if (parsed.findings || parsed.actionsTaken || parsed.failures || parsed.remainingWork) {
+                return {
+                    findings: Array.isArray(parsed.findings) ? parsed.findings : [],
+                    actionsTaken: Array.isArray(parsed.actionsTaken) ? parsed.actionsTaken : [],
+                    failures: Array.isArray(parsed.failures) ? parsed.failures : [],
+                    remainingWork: Array.isArray(parsed.remainingWork) ? parsed.remainingWork : [],
+                    exitReason: defaultExitReason,
+                    suggestedNextSteps: Array.isArray(parsed.suggestedNextSteps) ? parsed.suggestedNextSteps : undefined,
+                };
+            }
+        }
+    }
+    catch {
+        // JSON parse failed — fall through to fallback
+    }
+    // Fallback: LLM didn't produce valid JSON but we have text
+    if (defaultExitReason !== 'completed') {
+        return {
+            findings: [text.slice(0, 500)],
+            actionsTaken: [],
+            failures: ['Did not produce structured JSON summary'],
+            remainingWork: fallbackTask ? [fallbackTask] : [],
+            exitReason: defaultExitReason === 'timeout_graceful' ? 'timeout_hard' : defaultExitReason,
+        };
+    }
+    // For completed agents, don't force a structured report if they didn't produce one
+    return undefined;
+}
 //# sourceMappingURL=agent.js.map