neoagent 2.5.2-beta.9 → 3.0.1-beta.0

package/server/services/ai/loop/conversation_loop.js

@@ -56,6 +56,13 @@ const { enforceRateLimits } = require('../rate_limits');
 const { ToolRepetitionGuard } = require('../repetitionGuard');
 const { shortenRunId, summarizeForLog } = require('../logFormat');
 const { IterationBudget } = require('./iteration_budget');
+const {
+  buildBlankAfterToolFailureGuidance,
+  shouldContinueAfterBlankToolFailure,
+} = require('./blank_recovery');
+const {
+  shouldSendMessagingErrorFallback,
+} = require('./error_recovery');
 const {
   buildCompletionDecisionPrompt,
   buildGoalContractPrompt,
@@ -117,11 +124,16 @@ const {
   getAvailableTools: getAvailableToolsImpl,
   isReadOnlyToolCall: isReadOnlyToolCallImpl,
 } = require('./tool_dispatch');
+const {
+  isProgressToolCall,
+} = require('./progress_classification');
 const {
   normalizeOutgoingMessage,
   clampRunContext,
   joinSentMessages,
   buildBlankMessagingReplyPrompt,
+  buildMaxIterationWrapupPrompt,
+  buildProgressUpdatePrompt,
   buildDeterministicMessagingFallback,
   buildMessagingFailureScenario,
   buildDeterministicMessagingErrorReply,
@@ -129,10 +141,11 @@ const {
 } = require('../messagingFallback');
 const {
   classifyToolExecution,
+  isSubstantiveProgressToolName,
+  summarizeProgressToolExecutions,
   summarizeToolExecutions,
   summarizeAvailableTools,
   inferToolFailureMessage,
-  buildAutonomousRecoveryContext,
 } = require('../toolEvidence');
 const {
   buildMemoryConsolidationInstructions,
@@ -195,7 +208,7 @@ function buildErrorPatternGuidance(key, count) {
   // Immediate guidance on first occurrence for high-signal patterns that waste
   // multiple iterations before self-correcting.
   const immediateGuides = {
-    eisdir: 'That path is a directory (or a VM-only path like /tmp that read_file cannot reach). Use execute_command with `cat <path>` to read files inside VMs, or list_directory to inspect a directory.',
+    eisdir: 'That path is a directory or outside the workspace file-tool boundary. Use list_directory for workspace directories. Keep source files in the shared workspace before reading them with file tools.',
     owner_repo_format: 'The parameter "owner_repo" expects a single combined string like "NeoLabs-Systems/NeoAgent" — not separate owner/repo fields. Pass the full "owner/repo" as one value.',
   };
   if (immediateGuides[key]) {
@@ -205,9 +218,9 @@ function buildErrorPatternGuidance(key, count) {
 
   if (count < 3) return null;
   const guides = {
-    outside_workspace: 'read_file cannot access /tmp paths. Use execute_command with `cat <path>` instead.',
+    outside_workspace: 'read_file/read_files only access the shared workspace. Put the relevant files there, then use read_files/search_files/edit_file instead of repeatedly extracting snippets through shell commands.',
     enoent: 'That path does not exist. Use execute_command with `find . -name "..."` to locate the correct path first.',
-    bad_cwd: 'The VM home directory is not ~/. Use absolute paths starting from /tmp or discover the workspace root first.',
+    bad_cwd: 'The VM home directory is not ~/. Discover the workspace root with pwd/list_directory and keep working files there so file tools can inspect them.',
     not_found: 'This path or resource was not found. Try listing the parent directory or checking with a broader search first.',
   };
   const guide = guides[key];
@@ -217,8 +230,17 @@ function buildErrorPatternGuidance(key, count) {
 
 const OUTPUT_FINGERPRINT_TOOLS = /^(list_|search_|read_|get_|find_|github_list|github_get|github_search)/;
 
-function fingerprintOutput(toolName, result) {
-  if (!toolName || !OUTPUT_FINGERPRINT_TOOLS.test(toolName)) return null;
+function fingerprintOutput(toolName, result, toolArgs = {}) {
+  const name = String(toolName || '');
+  if (
+    !name
+    || (
+      !OUTPUT_FINGERPRINT_TOOLS.test(name)
+      && !(name === 'execute_command' && !isProgressToolCall(name, toolArgs))
+    )
+  ) {
+    return null;
+  }
   const raw = typeof result === 'string' ? result : JSON.stringify(result ?? '');
   if (raw.length < 200) return null;
   // djb2 hash over first 3000 chars — fast, collision-unlikely for our sizes
@@ -228,16 +250,37 @@ function fingerprintOutput(toolName, result) {
   return h >>> 0;
 }
 
-// Tools that represent concrete forward progress (write, create, send, update, run).
-// Anything NOT in this set is considered read-only for the analysis-paralysis gate.
-// execute_command counts as progress — it can do anything, including modify state.
-function isProgressTool(toolName) {
-  if (!toolName) return false;
-  // Neutral / bookkeeping — don't count either way
-  if (toolName === 'activate_tools' || toolName === 'save_widget_snapshot') return false;
-  // Explicitly read-only patterns
-  if (/^(list_|search_|read_file|get_file|find_files?|github_list|github_get|github_search|browser_get|browser_read)/.test(toolName)) return false;
-  return true;
+// Concise list of files/targets the run has already read or searched, so the
+// analysis-paralysis nudge can name them and tell the model not to re-read them.
+function summarizeReadTargets(toolExecutions = []) {
+  const targets = [];
+  const seen = new Set();
+  for (const item of toolExecutions) {
+    if (!item || item.stateChanged) continue; // only read-only steps
+    const input = item.input || {};
+    let target = '';
+    if (Array.isArray(input.files) && input.files.length) {
+      target = input.files
+        .map((file) => (typeof file === 'string' ? file : file?.path || file?.file_path || ''))
+        .filter(Boolean)
+        .slice(0, 3)
+        .join(', ');
+    } else if (typeof input.path === 'string' && input.path.trim()) {
+      target = input.path.trim();
+    } else if (typeof input.command === 'string') {
+      const files = input.command.match(/[\w./-]+\.(?:js|ts|tsx|jsx|py|dart|json|md|kt|c|h|ya?ml|sql|txt|sh)\b/g);
+      if (files && files.length) target = [...new Set(files)].slice(0, 2).join(', ');
+    } else if (typeof input.query === 'string' && input.query.trim()) {
+      target = `search:${input.query.trim().slice(0, 30)}`;
+    }
+    if (!target) continue;
+    const key = target.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    targets.push(target);
+    if (targets.length >= 8) break;
+  }
+  return targets.join('; ');
 }
 
 function cloneInterimHistory(history = []) {
@@ -556,9 +599,16 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
 
   const runTitle = generateTitle(userMessage);
   const initialRunMetadata = buildInitialRunMetadata(options);
-  db.prepare(`INSERT OR REPLACE INTO agent_runs(
+  db.prepare(`INSERT INTO agent_runs(
     id, user_id, agent_id, title, status, trigger_type, trigger_source, model, metadata_json
-  ) VALUES(?, ?, ?, ?, 'running', ?, ?, ?, ?)`).run(
+  ) VALUES(?, ?, ?, ?, 'running', ?, ?, ?, ?)
+  ON CONFLICT(id) DO UPDATE SET
+    status = 'running',
+    model = excluded.model,
+    updated_at = datetime('now'),
+    completed_at = NULL,
+    error = NULL,
+    metadata_json = COALESCE(agent_runs.metadata_json, excluded.metadata_json)`).run(
     runId,
     userId,
     agentId,
@@ -615,6 +665,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     steeringQueue: [],
     systemSteeringQueue: [],
     toolPids: new Set(),
+    subagentDepth: Math.max(0, Number(options.subagentDepth) || 0),
     repetitionGuard: new ToolRepetitionGuard(),
     seenOutputHashes: new Map(),
     consecutiveReadOnlyIterations: 0,
@@ -667,7 +718,13 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
   const mcpManager = app?.locals?.mcpManager || app?.locals?.mcpClient || engine.mcpManager;
   const integrationManager = app?.locals?.integrationManager || null;
   const mcpTools = mcpManager ? mcpManager.getAllTools(userId, { agentId }) : [];
-  const allTools = selectToolsForTask(userMessage, builtInTools, mcpTools, options);
+  const disallowedToolNames = new Set(
+    (Array.isArray(options.disallowedToolNames) ? options.disallowedToolNames : [])
+      .map((name) => String(name || '').trim())
+      .filter(Boolean),
+  );
+  const allTools = selectToolsForTask(userMessage, builtInTools, mcpTools, options)
+    .filter((tool) => !disallowedToolNames.has(tool?.name));
   let tools = allTools;
   const toolNames = allTools.map((tool) => tool.name).filter(Boolean);
   const coreToolStatus = {
@@ -686,7 +743,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
   console.info(
     `[Run ${shortenRunId(runId)}] tools total=${toolNames.length} builtIns=${builtInTools.length} mcp=${mcpTools.length} core=${JSON.stringify(coreToolStatus)}`
   );
-  const capabilityHealth = await getCapabilityHealth({ userId, agentId, app, engine: this });
+  const capabilityHealth = await getCapabilityHealth({ userId, agentId, app, engine });
   const capabilitySummary = summarizeCapabilityHealth(capabilityHealth);
   const integrationSummary = integrationManager?.summarizeConnectedProviders?.(userId, agentId) || '';
 
@@ -762,6 +819,62 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
   let compactionMetrics = [];
   let analysis = null;
   let plan = null;
+
+  // Model-authored progress updates: the messaging supervisor calls this to get a
+  // dynamic "what I'm doing right now" line instead of a hard-coded string. It runs
+  // a tiny tool-less model call over the current run activity. `provider`/`model` are
+  // `let` (closure tracks fallbacks) and `toolExecutions` is push-only.
+  if (triggerSource === 'messaging') {
+    const runMetaForCompose = engine.getRunMeta(runId);
+    if (runMetaForCompose) {
+      runMetaForCompose.composeProgressUpdate = async ({ stalled = false } = {}) => {
+        try {
+          const rm = engine.getRunMeta(runId);
+          const ledger = rm?.progressLedger || {};
+          // Real, specific evidence (actual commands + their output) so the update is
+          // grounded in what happened, not invented. Bare tool names make a weak model
+          // confabulate generic activity ("running the build", "training").
+          const recent = summarizeProgressToolExecutions(toolExecutions, 5);
+          const currentTool = isSubstantiveProgressToolName(ledger.currentTool)
+            ? ledger.currentTool
+            : '';
+          if (!recent && !currentTool) {
+            return '';
+          }
+          const priorUpdate = String(rm?.lastInterimMessage || '').trim();
+          const contextBlock = [
+            buildProgressUpdatePrompt(),
+            stalled ? 'This step has been running a while with no new progress; reassure the user you are still on it.' : '',
+            '',
+            `Original request: ${summarizeForLog(userMessage, 320)}`,
+            currentTool ? `Doing now: using ${currentTool}` : '',
+            recent ? `Actual recent tool activity (newest last) — describe ONLY this, do not extrapolate:\n${recent}` : '',
+            priorUpdate ? `Your previous update (say something different): ${summarizeForLog(priorUpdate, 160)}` : '',
+          ].filter(Boolean).join('\n');
+          // Reuse the run's real system prompt so the update follows the same voice and
+          // formatting guidelines as every other message (single source of truth).
+          const sysContent = [systemPrompt?.stable, systemPrompt?.dynamic].filter(Boolean).join('\n\n')
+            || 'You are a helpful assistant.';
+          const resp = await withModelCallTimeout(
+            provider.chat(
+              [
+                { role: 'system', content: sysContent },
+                { role: 'user', content: contextBlock },
+              ],
+              [],
+              { model, reasoningEffort: engine.getReasoningEffort(providerName, options) },
+            ),
+            options,
+            'Progress update compose',
+          );
+          return sanitizeModelOutput(resp.content || '', { model });
+        } catch (composeErr) {
+          console.warn(`[Run ${shortenRunId(runId)}] progress_update_compose failed: ${summarizeForLog(composeErr?.message || composeErr, 140)}`);
+          return '';
+        }
+      };
+    }
+  }
   let verification = null;
   let deliverableWorkflow = null;
   let deliverablePlan = null;
@@ -827,6 +940,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
 
     tools = selectInitialTools(allTools, analysis.suggested_tools, {
       widgetId: options.widgetId || null,
+      includeCoreFileTools: analysis.mode === 'execute' || analysis.mode === 'plan_execute',
     });
     engine.initializeToolRuntime(runId, allTools, tools, options);
     messages.push({
@@ -836,6 +950,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         buildToolCatalog(allTools),
         '',
         `Active tools: ${tools.map((tool) => tool.name).join(', ')}`,
+        'For workspace file inspection/editing, prefer read_files, read_file, search_files, list_directory, edit_file, replace_file_range, and write_file over shell cat/sed/python snippets. Use execute_command for git, tests, package managers, builds, and other shell-native actions.',
         'Use activate_tools with exact catalog names when another schema is required.',
       ].join('\n'),
     });
@@ -896,54 +1011,63 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     maxIterations = loopPolicy.maxIterations;
 
     if (options.skipDeliverableWorkflow !== true) {
-      const deliverableSelectionResult = await selectDeliverableWorkflow({
-        engine: this,
-        provider,
-        providerName,
-        model,
-        messages,
-        tools,
-        options: { ...options, runId, userId, agentId },
-      });
-      totalTokens += deliverableSelectionResult.usage || 0;
-      const selectedWorkflow = getDeliverableWorkflow(deliverableSelectionResult.selection.type);
-      if (selectedWorkflow?.canHandle(deliverableSelectionResult.selection)) {
-        deliverableWorkflow = {
-          workflow: selectedWorkflow,
-          selection: deliverableSelectionResult.selection,
-          request: selectedWorkflow.normalizeRequest({
-            ...deliverableSelectionResult.selection,
-            userMessage,
-          }),
-        };
-        deliverablePlan = selectedWorkflow.buildExecutionPlan(deliverableWorkflow.request, {
-          analysis,
+      try {
+        const deliverableSelectionResult = await selectDeliverableWorkflow({
+          engine,
+          provider,
+          providerName,
+          model,
+          messages,
           tools,
-          options,
-        });
-        await selectedWorkflow.run(deliverablePlan, {
-          engine: this,
-          userId,
-          agentId,
-          runId,
-          agentId,
-          app,
+          options: { ...options, runId, userId, agentId },
         });
-        engine.persistRunMetadata(runId, {
-          deliverableWorkflow: {
-            ...deliverableWorkflow.selection,
-            plan: deliverablePlan,
-          },
-        });
-        engine.updateRunGoalContract(runId, {
-          goal: deliverableWorkflow.selection.goal,
-        });
-        engine.recordRunEvent(userId, runId, 'deliverable_workflow_selected', {
-          type: deliverableWorkflow.selection.type,
-          confidence: deliverableWorkflow.selection.confidence,
-          goal: deliverableWorkflow.selection.goal,
-          requestedOutputs: deliverableWorkflow.selection.requestedOutputs,
+        totalTokens += deliverableSelectionResult.usage || 0;
+        const selectedWorkflow = getDeliverableWorkflow(deliverableSelectionResult.selection.type);
+        if (selectedWorkflow?.canHandle(deliverableSelectionResult.selection)) {
+          deliverableWorkflow = {
+            workflow: selectedWorkflow,
+            selection: deliverableSelectionResult.selection,
+            request: selectedWorkflow.normalizeRequest({
+              ...deliverableSelectionResult.selection,
+              userMessage,
+            }),
+          };
+          deliverablePlan = selectedWorkflow.buildExecutionPlan(deliverableWorkflow.request, {
+            analysis,
+            tools,
+            options,
+          });
+          await selectedWorkflow.run(deliverablePlan, {
+            engine,
+            userId,
+            agentId,
+            runId,
+            app,
+          });
+          engine.persistRunMetadata(runId, {
+            deliverableWorkflow: {
+              ...deliverableWorkflow.selection,
+              plan: deliverablePlan,
+            },
+          });
+          engine.updateRunGoalContract(runId, {
+            goal: deliverableWorkflow.selection.goal,
+          });
+          engine.recordRunEvent(userId, runId, 'deliverable_workflow_selected', {
+            type: deliverableWorkflow.selection.type,
+            confidence: deliverableWorkflow.selection.confidence,
+            goal: deliverableWorkflow.selection.goal,
+            requestedOutputs: deliverableWorkflow.selection.requestedOutputs,
+          }, { agentId });
+        }
+      } catch (error) {
+        engine.recordRunEvent(userId, runId, 'deliverable_workflow_skipped', {
+          reason: summarizeForLog(error?.message || error, 240),
         }, { agentId });
+        messages.push({
+          role: 'system',
+          content: 'The optional deliverable workflow classifier failed. Continue with the normal agent loop; do not stop or retry the whole run just because this classifier failed.',
+        });
       }
     }
 
@@ -1051,9 +1175,18 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         const readOnlyCount = engine.getRunMeta(runId)?.consecutiveReadOnlyIterations || 0;
         if (readOnlyCount >= 3) {
           const urgency = readOnlyCount >= 6 ? 'CRITICAL' : 'ACTION REQUIRED';
+          const alreadyRead = summarizeReadTargets(toolExecutions);
           messages.push({
             role: 'system',
-            content: `${urgency} — ${readOnlyCount} consecutive read-only turns: You have been gathering information for ${readOnlyCount} turns without writing, creating, sending, or running anything. You must take ONE concrete action this turn (create a file, open a PR, run a command that modifies state, send a message) or call task_complete to report what you found and why you cannot proceed. Do not read or list anything further.`,
+            content: [
+              `${urgency} — ${readOnlyCount} consecutive read-only turns with no concrete action.`,
+              alreadyRead
+                ? `You have ALREADY read/searched: ${alreadyRead}. Their output is in this conversation above — do not read or search them again; re-reading what you already have is the main way runs stall.`
+                : 'Do not re-read or re-search anything already in this conversation.',
+              'If you are repeatedly extracting evidence through low-level commands, switch to the available file/search/edit tools over the shared workspace.',
+              'Act on what you already know now: edit files, run a state-changing command, create the branch/PR, or send the result.',
+              'If you genuinely cannot proceed, call task_complete with your best answer or a concrete blocker. Deciding to finish is a valid action; continuing to gather is not.',
+            ].join(' '),
           });
         }
       }
@@ -1268,6 +1401,23 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         })) {
           break;
         }
+        if (shouldContinueAfterBlankToolFailure({
+          lastContent,
+          failedStepCount,
+          remainingIterations: iterationBudget.remaining,
+          toolExecutions,
+        })) {
+          engine.recordRunEvent(userId, runId, 'blank_after_tool_failure_continued', {
+            iteration,
+            remainingIterations: iterationBudget.remaining,
+          }, { agentId });
+          messages.push({
+            role: 'system',
+            content: buildBlankAfterToolFailureGuidance(toolExecutions),
+          });
+          lastContent = '';
+          continue;
+        }
         const loopDecision = await engine.decideLoopState({
           provider,
           providerName,
@@ -1378,9 +1528,16 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         }, {
           verified: true,
         });
+        if (analysis.mode === 'execute' || analysis.mode === 'plan_execute') {
+          const iterMeta = engine.getRunMeta(runId);
+          if (iterMeta) {
+            iterMeta.consecutiveReadOnlyIterations = (iterMeta.consecutiveReadOnlyIterations || 0) + 1;
+          }
+        }
         continue;
       }
 
+      let iterationConcreteProgress = false;
       for (const toolCall of response.toolCalls) {
         if (engine.isRunStopped(runId)) break;
         stepIndex++;
@@ -1595,6 +1752,9 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
 
         const execution = classifyToolExecution(toolName, toolArgs, toolResult, toolErrorMessage);
         execution.input = toolArgs;
+        if (execution.stateChanged && isProgressToolCall(toolName, toolArgs)) {
+          iterationConcreteProgress = true;
+        }
         repetitionGuard?.observe(toolName, toolArgs, toolResult);
         execution.artifacts = await extractArtifactsFromResult(toolName, toolResult);
         toolExecutions.push(execution);
@@ -1684,7 +1844,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           // Output fingerprint guard: steer away from re-fetching data already seen.
           if (!toolErrorMessage) {
             const currentRunMeta = engine.getRunMeta(runId);
-            const fp = fingerprintOutput(toolName, toolResult);
+            const fp = fingerprintOutput(toolName, toolResult, toolArgs);
             if (fp !== null && currentRunMeta?.seenOutputHashes) {
               const prior = currentRunMeta.seenOutputHashes.get(fp);
               if (prior) {
@@ -1694,24 +1854,6 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
                 });
               } else {
                 currentRunMeta.seenOutputHashes.set(fp, { toolName, iteration });
-                // External state: persist large read results to disk so the
-                // model can reference them after context compaction without
-                // re-fetching. Only for significant payloads.
-                const persistRaw = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult ?? '');
-                if (persistRaw.length >= 1000 && runId) {
-                  const persistPath = `/tmp/run-${runId.slice(0, 8)}-${toolName}.json`;
-                  try {
-                    require('fs').writeFileSync(persistPath, persistRaw.slice(0, 40000));
-                    if (!currentRunMeta.persistedDataPaths) currentRunMeta.persistedDataPaths = [];
-                    if (!currentRunMeta.persistedDataPaths.includes(persistPath)) {
-                      currentRunMeta.persistedDataPaths.push(persistPath);
-                      messages.push({
-                        role: 'system',
-                        content: `Data from "${toolName}" (iteration ${iteration}) persisted to ${persistPath}. If context compacts and you need this data again, use execute_command with \`cat ${persistPath}\` instead of re-fetching.`,
-                      });
-                    }
-                  } catch { /* non-fatal — disk full or permissions */ }
-                }
               }
             }
           }
@@ -1782,8 +1924,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         && (analysis.mode === 'execute' || analysis.mode === 'plan_execute')) {
         const iterMeta = engine.getRunMeta(runId);
         if (iterMeta) {
-          const calledProgress = response.toolCalls.some((tc) => isProgressTool(tc.function?.name || ''));
-          iterMeta.consecutiveReadOnlyIterations = calledProgress
+          iterMeta.consecutiveReadOnlyIterations = iterationConcreteProgress
             ? 0
             : (iterMeta.consecutiveReadOnlyIterations || 0) + 1;
         }
@@ -1796,20 +1937,41 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     }
 
     if (engine.isRunStopped(runId)) {
-      db.prepare('UPDATE agent_runs SET status = ?, updated_at = datetime(\'now\'), completed_at = datetime(\'now\') WHERE id = ?')
-        .run('stopped', runId);
+      const stoppedRunMeta = engine.getRunMeta(runId);
+      const terminalStatus = stoppedRunMeta?.status === 'interrupted' ? 'interrupted' : 'stopped';
+      const stopReason = stoppedRunMeta?.stopReason || null;
+      db.prepare(
+        `UPDATE agent_runs
+         SET status = ?,
+             error = COALESCE(?, error),
+             updated_at = datetime('now'),
+             completed_at = datetime('now')
+         WHERE id = ?`
+      ).run(terminalStatus, stopReason, runId);
       console.warn(
-        `[Run ${shortenRunId(runId)}] stopped trigger=${triggerSource} steps=${stepIndex} tokens=${totalTokens}`
+        `[Run ${shortenRunId(runId)}] ${terminalStatus} trigger=${triggerSource} steps=${stepIndex} tokens=${totalTokens}`
       );
+      engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
       engine.stopMessagingProgressSupervisor(runId);
       engine.activeRuns.delete(runId);
-      engine.emit(userId, 'run:stopped', { runId, triggerSource });
-      engine.recordRunEvent(userId, runId, 'run_stopped', {
+      engine.emit(userId, terminalStatus === 'interrupted' ? 'run:interrupted' : 'run:stopped', {
+        runId,
         triggerSource,
-        totalTokens,
-        iterations: iteration,
-      }, { agentId });
-      return { runId, content: '', totalTokens, iterations: iteration, status: 'stopped' };
+        reason: stopReason,
+      });
+      engine.recordRunEvent(
+        userId,
+        runId,
+        terminalStatus === 'interrupted' ? 'run_interrupted' : 'run_stopped',
+        {
+          triggerSource,
+          totalTokens,
+          iterations: iteration,
+          reason: stopReason,
+        },
+        { agentId },
+      );
+      return { runId, content: '', totalTokens, iterations: iteration, status: terminalStatus };
     }
 
     const runMeta = engine.activeRuns.get(runId);
@@ -1822,6 +1984,54 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     const messagingSent = runMeta?.messagingSent || false;
     const lastToolWasMessaging = runMeta?.lastToolName === 'send_message' || runMeta?.lastToolName === 'make_call';
 
+    // Hermes _handle_max_iterations: if the run exhausted its step budget without a
+    // judged completion, the model's last text is usually a mid-thought fragment
+    // ("let me inline everything:"). Do one tool-less wrap-up call so the user gets a
+    // real final answer instead of that fragment.
+    const budgetExhaustedWithoutCompletion = triggerSource === 'messaging'
+      && !directAnswerEligible
+      && !messagingSent
+      && !runMeta?.terminalInterim
+      && iteration >= maxIterations;
+    if (budgetExhaustedWithoutCompletion) {
+      console.warn(`[Run ${shortenRunId(runId)}] max_iteration_wrapup model=${model} iteration=${iteration}/${maxIterations}`);
+      try {
+        const wrapResponse = await withModelCallTimeout(
+          provider.chat(
+            sanitizeConversationMessages([
+              ...messages,
+              { role: 'system', content: buildMaxIterationWrapupPrompt(options?.source || null) },
+            ]),
+            [],
+            { model, reasoningEffort: engine.getReasoningEffort(providerName, options) },
+          ),
+          options,
+          'Max-iteration wrap-up',
+        );
+        totalTokens += wrapResponse.usage?.totalTokens || 0;
+        const wrapText = sanitizeModelOutput(wrapResponse.content || '', { model });
+        // On budget exhaustion the model's last text is an untrustworthy mid-thought
+        // fragment. Replace it with the wrap-up answer, or a clean deterministic
+        // fallback if the wrap-up came back empty — never deliver the fragment.
+        const usableWrap = normalizeOutgoingMessage(wrapText, options?.source || null);
+        lastContent = usableWrap
+          ? wrapText
+          : buildDeterministicMessagingFallback({ failedStepCount, stepIndex, toolExecutions });
+        messages.push({ role: 'assistant', content: lastContent });
+        if (conversationId) {
+          db.prepare('INSERT INTO conversation_messages (conversation_id, role, content, tokens) VALUES (?, ?, ?, ?)')
+            .run(conversationId, 'assistant', lastContent, usableWrap ? (wrapResponse.usage?.totalTokens || 0) : 0);
+        }
+        engine.recordRunEvent(userId, runId, 'max_iteration_wrapup_delivered', {
+          iteration, maxIterations, stepIndex, source: usableWrap ? 'model' : 'deterministic',
+        }, { agentId });
+      } catch (wrapErr) {
+        console.warn(`[Run ${shortenRunId(runId)}] max_iteration_wrapup failed: ${summarizeForLog(wrapErr?.message || wrapErr, 180)}`);
+        lastContent = buildDeterministicMessagingFallback({ failedStepCount, stepIndex, toolExecutions });
+        messages.push({ role: 'assistant', content: lastContent });
+      }
+    }
+
     if (triggerSource === 'messaging' && !normalizeOutgoingMessage(lastContent, options?.source || null) && !messagingSent) {
       // Simplified blank reply recovery: one model call with direct instruction,
       // then fall back to a deterministic message. No multi-attempt LLM loop.
@@ -1852,37 +2062,24 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         console.warn(`[Run ${shortenRunId(runId)}] blank_reply_recovery failed: ${summarizeForLog(recoverErr?.message || recoverErr, 180)}`);
       }
       totalTokens += recoveredTokens;
-      if (!normalizeOutgoingMessage(lastContent, options?.source || null)) {
+      // The loop has already exited, so we cannot keep working: deliver the model's
+      // own wrap-up (it summarizes what it tried / where it got blocked from the run
+      // evidence) instead of second-guessing it into a generic blob. Only fall back to
+      // a deterministic message when the model returned nothing usable.
+      const recoveredVisible = Boolean(normalizeOutgoingMessage(lastContent, options?.source || null));
+      if (!recoveredVisible) {
         lastContent = buildDeterministicMessagingFallback({ failedStepCount, stepIndex, toolExecutions });
       }
       if (normalizeOutgoingMessage(lastContent, options?.source || null)) {
-        const recoveryDecision = await engine.decideLoopState({
-          provider,
-          providerName,
-          model,
-          messages,
-          analysis,
-          plan,
-          tools,
-          toolExecutions,
-          lastReply: lastContent,
-          iteration,
-          maxIterations,
-          options: { ...options, triggerSource, runId, userId, agentId },
-          messagingSent: false,
-        });
-        totalTokens += recoveryDecision.usage || 0;
-        engine.recordRunEvent(userId, runId, 'blank_reply_recovery_checked', {
-          status: recoveryDecision.decision.status,
-          reason: recoveryDecision.decision.reason,
+        engine.recordRunEvent(userId, runId, 'blank_reply_recovery_delivered', {
+          source: recoveredVisible ? 'model' : 'deterministic',
+          stepIndex,
+          failedStepCount,
         }, { agentId });
-        if (recoveryDecision.decision.status === 'continue') {
-          throw new Error('Messaging run ended without a judged terminal reply.');
-        }
         messages.push({ role: 'assistant', content: lastContent });
         if (conversationId) {
           db.prepare('INSERT INTO conversation_messages (conversation_id, role, content, tokens) VALUES (?, ?, ?, ?)')
-            .run(conversationId, 'assistant', lastContent, recoveredTokens);
+            .run(conversationId, 'assistant', lastContent, recoveredVisible ? recoveredTokens : 0);
         }
       }
     }
@@ -1910,10 +2107,28 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           stepIndex,
           failedStepCount,
         }, { agentId });
-        throw new Error(`Iteration budget exhausted before judged completion after ${maxIterations} iterations.`);
+        if (triggerSource === 'messaging') {
+          lastContent = buildDeterministicMessagingFallback({ failedStepCount, stepIndex, toolExecutions });
+          messages.push({ role: 'assistant', content: lastContent });
+          if (conversationId) {
+            db.prepare('INSERT INTO conversation_messages (conversation_id, role, content, tokens) VALUES (?, ?, ?, ?)')
+              .run(conversationId, 'assistant', lastContent, 0);
+          }
+        } else {
+          throw new Error(`Iteration budget exhausted before judged completion after ${maxIterations} iterations.`);
+        }
       }
       if (stepIndex > 0 && !lastToolWasMessaging && iteration < maxIterations) {
-        throw new Error('Run ended without an explicit completion or blocker reply.');
+        if (triggerSource === 'messaging') {
+          lastContent = buildDeterministicMessagingFallback({ failedStepCount, stepIndex, toolExecutions });
+          messages.push({ role: 'assistant', content: lastContent });
+          if (conversationId) {
+            db.prepare('INSERT INTO conversation_messages (conversation_id, role, content, tokens) VALUES (?, ?, ?, ?)')
+              .run(conversationId, 'assistant', lastContent, 0);
+          }
+        } else {
+          throw new Error('Run ended without an explicit completion or blocker reply.');
+        }
       }
     }
 
@@ -2156,149 +2371,73 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     }
 
     const runMeta = engine.activeRuns.get(runId);
-    const retryCount = Number(options.messagingAutonomousRetryCount || 0);
-    // Rate-limit errors (429) must not trigger messaging retries: the model
-    // won't be available in the milliseconds between retries, so spawning new
-    // runs just compounds the rate-limit pressure with no benefit.
-    const isRateLimitError = /429|rate.?limit|free-models-per/i.test(String(err?.message || ''));
-    const canRetryMessagingRun = (
-      triggerSource === 'messaging'
-      && options.source
-      && options.chatId
-      && runMeta?.finalDeliverySent !== true
-      && runMeta?.messagingSent !== true
-      && err?.disableAutonomousRetry !== true
-      && !isRateLimitError
-      && retryCount < engine.getMessagingRetryLimit(maxIterations)
-    );
-
-    if (canRetryMessagingRun) {
-      const recoveryContext = buildAutonomousRecoveryContext({
-        err,
-        toolExecutions,
-        tools,
-        userMessage,
-        visibleMessageSent: Boolean(
-          runMeta?.lastSentMessage
-          || runMeta?.lastInterimMessage
-          || runMeta?.messagingSent === true
-        ),
-      });
-      db.prepare('UPDATE agent_runs SET status = ?, error = ?, updated_at = datetime(\'now\') WHERE id = ?')
-        .run('retrying', err.message, runId);
-      console.warn(
-        `[Run ${shortenRunId(runId)}] retrying_messaging_attempt=${retryCount + 1} reason=${summarizeForLog(err.message, 140)}`
-      );
-      engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
-      engine.stopMessagingProgressSupervisor(runId);
-      engine.activeRuns.delete(runId);
-      engine.emit(userId, 'run:interim', {
-        runId,
-        message: 'Retrying internally after a transient failure.',
-        phase: 'retrying'
-      });
-
-      const retryOptions = {
-        ...options,
-        messagingAutonomousRetryCount: retryCount + 1,
-        messagingRetryState: {
-          lastFinalMessage: String(runMeta?.lastSentMessage || options?.messagingRetryState?.lastFinalMessage || '').trim(),
-          explicitMessageSent: runMeta?.explicitMessageSent === true || options?.messagingRetryState?.explicitMessageSent === true,
-          interimHistory: cloneInterimHistory([
-            ...(Array.isArray(options?.messagingRetryState?.interimHistory) ? options.messagingRetryState.interimHistory : []),
-            ...(Array.isArray(runMeta?.interimMessages) ? runMeta.interimMessages : []),
-          ]),
-          goalContract: mergeGoalContracts(
-            options?.messagingRetryState?.goalContract || null,
-            runMeta?.goalContract || null,
-          ),
-          lastUserVisibleUpdateAt: runMeta?.progressLedger?.lastUserVisibleUpdateAt || options?.messagingRetryState?.lastUserVisibleUpdateAt || null,
-          lastFinalDeliveryAt: runMeta?.progressLedger?.lastFinalDeliveryAt || options?.messagingRetryState?.lastFinalDeliveryAt || null,
-          heartbeatCount: Number(runMeta?.progressLedger?.heartbeatCount || options?.messagingRetryState?.heartbeatCount || 0),
-          progressState: runMeta?.progressLedger?.progressState || options?.messagingRetryState?.progressState || 'active',
-          lastVerifiedProgressAt: runMeta?.progressLedger?.lastVerifiedProgressAt || options?.messagingRetryState?.lastVerifiedProgressAt || null,
-        },
-        context: {
-          ...(options.context || {}),
-          additionalContext: [
-            options.context?.additionalContext || '',
-            recoveryContext,
-          ].filter(Boolean).join('\n\n')
-        }
-      };
-      delete retryOptions.runId;
-
-      return engine.runWithModel(userId, userMessage, retryOptions, _modelOverride);
-    }
 
     const deliverableFailureResponse = err?.deliverableResult?.summary
       || err?.deliverableValidation?.summary
       || '';
     let messagingFailureContent = '';
     let sendSucceeded = false;
-    if (triggerSource === 'messaging' && options.source && options.chatId) {
-      if (!runMeta?.finalDeliverySent && !runMeta?.messagingSent) {
-        const manager = engine.messagingManager;
-        if (manager) {
-          const failureScenario = buildMessagingFailureScenario({
+    if (shouldSendMessagingErrorFallback({ triggerSource, options, runMeta })) {
+      const manager = engine.messagingManager;
+      if (manager) {
+        const failureScenario = buildMessagingFailureScenario({
+          err,
+          failedStepCount,
+          stepIndex,
+          toolExecutions,
+        });
+        try {
+          const failedMessage = sanitizeConversationMessages([
+            ...messages,
+            {
+              role: 'system',
+              content: `The run encountered a runtime error and cannot continue reliably. Use the actual run scenario below to explain the blocker naturally.\n\nScenario:\n${failureScenario || 'No additional scenario details were captured.'}\n\nDo not call tools. Write exactly one short user message. Do not ask the user to resend or restate the same task. Only ask the user for something if a specific external input, permission, or configuration change is actually required. Do not promise future work unless it will happen automatically before this reply is sent.\n\n${buildPlatformFormattingGuide(options?.source || null)}`
+            }
+          ]);
+          const modelReply = await withModelCallTimeout(
+            provider.chat(failedMessage, [], {
+              model,
+              reasoningEffort: engine.getReasoningEffort(providerName, options)
+            }),
+            options,
+            'Messaging failure reply',
+          );
+          const drafted = sanitizeModelOutput(modelReply.content || '', { model });
+          if (normalizeOutgoingMessage(drafted, options?.source || null)) {
+            messagingFailureContent = drafted.trim();
+          }
+        } catch {
+          // Fall back to deterministic text below.
+        }
+
+        if (!messagingFailureContent) {
+          messagingFailureContent = buildDeterministicMessagingErrorReply({
             err,
             failedStepCount,
             stepIndex,
             toolExecutions,
           });
-          try {
-            const failedMessage = sanitizeConversationMessages([
-              ...messages,
-              {
-                role: 'system',
-                content: `The run encountered a runtime error and cannot continue reliably. Use the actual run scenario below to explain the blocker naturally.\n\nScenario:\n${failureScenario || 'No additional scenario details were captured.'}\n\nDo not call tools. Write exactly one short user message. Do not ask the user to resend or restate the same task. Only ask the user for something if a specific external input, permission, or configuration change is actually required. Do not promise future work unless it will happen automatically before this reply is sent.\n\n${buildPlatformFormattingGuide(options?.source || null)}`
-              }
-            ]);
-            const modelReply = await withModelCallTimeout(
-              provider.chat(failedMessage, [], {
-                model,
-                reasoningEffort: engine.getReasoningEffort(providerName, options)
-              }),
-              options,
-              'Messaging failure reply',
-            );
-            const drafted = sanitizeModelOutput(modelReply.content || '', { model });
-            if (normalizeOutgoingMessage(drafted, options?.source || null)) {
-              messagingFailureContent = drafted.trim();
-            }
-          } catch {
-            // Fall back to deterministic text below.
-          }
-
-          if (!messagingFailureContent) {
-            messagingFailureContent = buildDeterministicMessagingErrorReply({
-              err,
-              failedStepCount,
-              stepIndex,
-              toolExecutions,
-            });
-          }
+        }
 
-          try {
-            const deliveryResult = await manager.sendMessage(
-              userId,
-              options.source,
-              options.chatId,
-              messagingFailureContent,
-              { runId, agentId },
-            );
-            requireSuccessfulMessagingDelivery(deliveryResult, 'Messaging failure delivery');
-            sendSucceeded = true;
-            if (runMeta) {
-              runMeta.lastSentMessage = messagingFailureContent;
-              if (!Array.isArray(runMeta.sentMessages)) runMeta.sentMessages = [];
-              runMeta.sentMessages.push(messagingFailureContent);
-            }
-            engine.markRunFinalDelivery(runId, messagingFailureContent);
-          } catch (sendErr) {
-            console.error('[Engine] Messaging error fallback failed:', sendErr.message);
-            messagingFailureContent = '';
+        try {
+          const deliveryResult = await manager.sendMessage(
+            userId,
+            options.source,
+            options.chatId,
+            messagingFailureContent,
+            { runId, agentId },
+          );
+          requireSuccessfulMessagingDelivery(deliveryResult, 'Messaging failure delivery');
+          sendSucceeded = true;
+          if (runMeta) {
+            runMeta.lastSentMessage = messagingFailureContent;
+            if (!Array.isArray(runMeta.sentMessages)) runMeta.sentMessages = [];
+            runMeta.sentMessages.push(messagingFailureContent);
           }
+          engine.markRunFinalDelivery(runId, messagingFailureContent);
+        } catch (sendErr) {
+          console.error('[Engine] Messaging error fallback failed:', sendErr.message);
+          messagingFailureContent = '';
         }
       }
     }