neoagent 3.0.1-beta.2 → 3.0.1-beta.21

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

@@ -49,7 +49,7 @@ const {
   selectDeliverableWorkflow,
   validateDeliverableExecution,
 } = require('../deliverables');
-const { buildLoopPolicy, resolveToolResultLimits } = require('../loopPolicy');
+const { buildLoopPolicy, resolveToolResultLimits, resolveChurnNudgeThreshold } = require('../loopPolicy');
 const { globalHooks } = require('../hooks');
 const { normalizeCompletionConfidence, shouldAcceptTaskComplete } = require('../completion');
 const { enforceRateLimits } = require('../rate_limits');
@@ -58,7 +58,10 @@ const { shortenRunId, summarizeForLog } = require('../logFormat');
 const { IterationBudget } = require('./iteration_budget');
 const {
   buildBlankAfterToolFailureGuidance,
+  buildRecoverableToolFailureGuidance,
+  isRecoverableInternalToolFailure,
   shouldContinueAfterBlankToolFailure,
+  shouldContinueAfterRecoverableToolFailure,
 } = require('./blank_recovery');
 const {
   shouldSendMessagingErrorFallback,
@@ -210,6 +213,9 @@ function buildErrorPatternGuidance(key, count) {
   // multiple iterations before self-correcting.
   const immediateGuides = {
     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.',
+    enoent: 'That path does not exist. Do not keep retrying the same missing file. Locate the correct file first with list_directory/search_files or verify whether the evidence only exists in the user-provided logs.',
+    outside_workspace: 'That path is outside the shared workspace. Use the workspace root and its file tools, or rely on the user-provided evidence if the file only exists on another server.',
+    bad_cwd: 'The current working directory is wrong for that path. Reconfirm the workspace root with pwd/list_directory before reading files.',
     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]) {
@@ -284,6 +290,24 @@ function summarizeReadTargets(toolExecutions = []) {
   return targets.join('; ');
 }
 
+function buildNoProgressWrapupPrompt({ readOnlyCount = 0, alreadyRead = '', platform = null } = {}) {
+  return [
+    `No-progress limit reached after ${Math.max(0, Number(readOnlyCount) || 0)} consecutive turns without substantive progress.`,
+    alreadyRead ? `Already inspected/searched: ${alreadyRead}.` : '',
+    'This is the final turn for this run. Do not call tools.',
+    'From the existing evidence, return the concrete result, a no-op/no-change answer, or a clear blocker.',
+    'If an external site, service, permission, unavailable target, or missing user input prevents completion, say that clearly and stop.',
+    buildMaxIterationWrapupPrompt(platform),
+  ].filter(Boolean).join('\n\n');
+}
+
+function isDeliveryTerminated(runMeta, deliveryState) {
+  return runMeta?.noResponse === true
+    || deliveryState?.noResponse === true
+    || runMeta?.finalDeliverySent === true
+    || deliveryState?.finalDeliverySent === true;
+}
+
 function cloneInterimHistory(history = []) {
   if (!Array.isArray(history)) return [];
   return history.map((item) => ({
@@ -483,6 +507,7 @@ async function getFailureFallbackModelId(userId, agentId, currentModelId, prefer
   const pool = enabledIds.length > 0
     ? availableModels.filter((model) => enabledIds.includes(model.id))
     : availableModels;
+  const fallbackSearchPool = pool.length > 0 ? pool : availableModels;
   const currentModel = pool.find((model) => model.id === currentModelId)
     || availableModels.find((model) => model.id === currentModelId)
     || null;
@@ -493,27 +518,26 @@ async function getFailureFallbackModelId(userId, agentId, currentModelId, prefer
   const isProviderRateLimit = /429|rate.?limit|free-models-per/i.test(String(failureError?.message || ''));
 
   if (preferredFallbackId && preferredFallbackId !== currentModelId && !isProviderRateLimit) {
-    const preferred = pool.find((model) => model.id === preferredFallbackId)
+    const preferred = fallbackSearchPool.find((model) => model.id === preferredFallbackId)
       || availableModels.find((model) => model.id === preferredFallbackId);
     if (preferred) return preferred.id;
   }
 
   if (currentModel?.provider) {
-    const differentProvider = pool.find((model) => model.id !== currentModelId && model.provider !== currentModel.provider)
-      || availableModels.find((model) => model.id !== currentModelId && model.provider !== currentModel.provider);
+    const differentProvider = fallbackSearchPool.find((model) =>
+      model.id !== currentModelId && model.provider !== currentModel.provider);
     if (differentProvider) return differentProvider.id;
   }
 
   // If no different-provider model exists, still try the preferred fallback
   // even on rate limits (it's better than nothing).
   if (preferredFallbackId && preferredFallbackId !== currentModelId) {
-    const preferred = pool.find((model) => model.id === preferredFallbackId)
+    const preferred = fallbackSearchPool.find((model) => model.id === preferredFallbackId)
       || availableModels.find((model) => model.id === preferredFallbackId);
     if (preferred) return preferred.id;
   }
 
-  const differentModel = pool.find((model) => model.id !== currentModelId)
-    || availableModels.find((model) => model.id !== currentModelId);
+  const differentModel = fallbackSearchPool.find((model) => model.id !== currentModelId);
   return differentModel?.id || null;
 }
 
@@ -529,13 +553,25 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
   const agentId = resolveAgentId(userId, options.agentId || options.agent_id || null);
   ensureDefaultAiSettings(userId, agentId);
   const aiSettings = getAiSettings(userId, agentId);
-
-  enforceRateLimits(userId);
-
   const runId = options.runId || uuidv4();
   const conversationId = options.conversationId;
   const app = options.app || engine.app;
   const triggerSource = options.triggerSource || 'web';
+  let provider = null;
+  let model = null;
+  let providerName = null;
+  let messages = [];
+  let iteration = 0;
+  let totalTokens = 0;
+  let lastContent = '';
+  let stepIndex = 0;
+  let failedStepCount = 0;
+  let toolExecutions = [];
+  let deliverableWorkflow = null;
+
+  const { releaseReservation } = enforceRateLimits(userId);
+
+  try {
   const historyWindow = Math.max(
     1,
     Number(options.historyWindow || aiSettings.chat_history_window) || aiSettings.chat_history_window,
@@ -563,9 +599,9 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     _modelOverride,
     providerStatusConfig
   );
-  let provider = selectedProvider.provider;
-  let model = selectedProvider.model;
-  let providerName = selectedProvider.providerName;
+  provider = selectedProvider.provider;
+  model = selectedProvider.model;
+  providerName = selectedProvider.providerName;
   const switchToFallbackModel = async (failedModel, error, phase) => {
     const fallbackModelId = await getFailureFallbackModelId(userId, agentId, failedModel, aiSettings.fallback_model_id, error);
     if (!fallbackModelId || fallbackModelId === failedModel) return false;
@@ -779,7 +815,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     historyMessages = (options.priorMessages || []).slice(-historyWindow).filter((pm) => pm.role && pm.content);
   }
 
-  let messages = engine.buildContextMessages(systemPrompt, summaryMessage, historyMessages, recallMsg);
+  messages = engine.buildContextMessages(systemPrompt, summaryMessage, historyMessages, recallMsg);
   if (capabilitySummary) {
     messages.push({ role: 'system', content: `[Capability health]\n${capabilitySummary}` });
   }
@@ -809,14 +845,14 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       .run(conversationId, 'user', userMessage);
   }
 
-  let iteration = 0;
-  let totalTokens = 0;
-  let lastContent = '';
-  let stepIndex = 0;
-  let failedStepCount = 0;
+  iteration = 0;
+  totalTokens = 0;
+  lastContent = '';
+  stepIndex = 0;
+  failedStepCount = 0;
   let modelFailureRecoveries = 0;
   let promptMetrics = {};
-  let toolExecutions = [];
+  toolExecutions = [];
   let compactionMetrics = [];
   let analysis = null;
   let plan = null;
@@ -877,15 +913,14 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     }
   }
   let verification = null;
-  let deliverableWorkflow = null;
+  deliverableWorkflow = null;
   let deliverablePlan = null;
   let deliverableArtifacts = [];
   let deliverableValidation = null;
   let directAnswerEligible = false;
   let analysisUsage = 0;
 
-  try {
-    if (options.skipTaskAnalysis === true) {
+  if (options.skipTaskAnalysis === true) {
       analysis = buildSkipTaskAnalysisResult(options.forceMode);
     } else {
       const analysisResult = await runWithModelFallback('task analysis', () => engine.analyzeTask({
@@ -1169,17 +1204,163 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       messages = steeringAtLoopStart.messages;
       messages = sanitizeConversationMessages(messages);
 
-      // Analysis-paralysis gate: fire at the start of every iteration where
-      // the agent has spent N turns only reading/listing/searching without
-      // taking any concrete action. Escalates in urgency each turn.
+      // Analysis-paralysis gate: AI self-assesses at churnNudgeThreshold; hard
+      // force-wrap-up fires at maxConsecutiveReadOnlyIterations unconditionally.
       if (analysis.mode === 'execute' || analysis.mode === 'plan_execute') {
         const readOnlyCount = engine.getRunMeta(runId)?.consecutiveReadOnlyIterations || 0;
-        if (readOnlyCount >= 3) {
-          const alreadyRead = summarizeReadTargets(toolExecutions);
-          messages.push({
-            role: 'system',
-            content: buildReadOnlyChurnGuidance({ readOnlyCount, alreadyRead }),
-          });
+        const iterMeta = engine.getRunMeta(runId);
+        const latestFailedExecution = toolExecutions.length > 0
+          ? [...toolExecutions].reverse().find((item) => item && item.ok === false) || null
+          : null;
+
+        if (readOnlyCount >= 2) {
+          const runGoalCtx = resolveRunGoalContext(engine.getRunMeta(runId), analysis, plan);
+          const churnNudgeThreshold = resolveChurnNudgeThreshold(runGoalCtx.goalContract);
+
+          let triggerForceWrapup = false;
+          let forceWrapupSource = 'hard_limit';
+          let alreadyRead = '';
+
+          if (readOnlyCount >= loopPolicy.maxConsecutiveReadOnlyIterations) {
+            if (
+              isRecoverableInternalToolFailure(latestFailedExecution)
+              && iterMeta
+              && iterMeta.recoverableReadOnlyDeferralUsed !== true
+            ) {
+              iterMeta.recoverableReadOnlyDeferralUsed = true;
+              iterMeta.consecutiveReadOnlyIterations = Math.max(0, loopPolicy.maxConsecutiveReadOnlyIterations - 2);
+              messages.push({
+                role: 'system',
+                content: buildRecoverableToolFailureGuidance(toolExecutions),
+              });
+              engine.recordRunEvent(userId, runId, 'read_only_wrapup_deferred_for_recovery', {
+                iteration,
+                readOnlyCount,
+                toolName: latestFailedExecution?.toolName || null,
+              }, { agentId });
+              continue;
+            }
+            alreadyRead = summarizeReadTargets(toolExecutions);
+            triggerForceWrapup = true;
+          } else if (readOnlyCount >= churnNudgeThreshold) {
+            alreadyRead = summarizeReadTargets(toolExecutions);
+            let churnResult;
+            try {
+              churnResult = await engine.assessChurnState({
+                provider,
+                providerName,
+                model,
+                messages,
+                analysis,
+                plan,
+                toolExecutions,
+                readOnlyCount,
+                alreadyRead,
+                iteration,
+                options: { ...options, triggerSource, runId, userId, agentId },
+              });
+            } catch (churnErr) {
+              console.warn(`[Run ${shortenRunId(runId)}] churn_assessment failed: ${summarizeForLog(churnErr?.message || churnErr, 120)}`);
+              churnResult = { assessment: { assessment: 'churn', reason: '' }, usage: 0 };
+            }
+            totalTokens += churnResult.usage || 0;
+            engine.recordRunEvent(userId, runId, 'churn_assessment', {
+              assessment: churnResult.assessment.assessment,
+              reason: churnResult.assessment.reason,
+              readOnlyCount,
+              churnNudgeThreshold,
+              iteration,
+            }, { agentId });
+
+            const churnVerdict = churnResult.assessment.assessment;
+            if (churnVerdict === 'blocked') {
+              triggerForceWrapup = true;
+              forceWrapupSource = 'ai_blocked';
+            } else if (churnVerdict === 'progressing') {
+              // Model is genuinely on track — partially reset so it gets
+              // re-assessed after one more read-only turn rather than immediately.
+              const iterMeta = engine.getRunMeta(runId);
+              if (iterMeta) {
+                iterMeta.consecutiveReadOnlyIterations = Math.max(0, churnNudgeThreshold - 1);
+              }
+            } else {
+              // 'churn' — model acknowledges it is spinning; inject the nudge
+              // so it can course-correct in the next iteration.
+              messages.push({
+                role: 'system',
+                content: buildReadOnlyChurnGuidance({ readOnlyCount, alreadyRead }),
+              });
+            }
+          }
+
+          if (triggerForceWrapup) {
+            console.warn(
+              `[Run ${shortenRunId(runId)}] no_progress_wrapup source=${forceWrapupSource} readOnlyCount=${readOnlyCount}`
+            );
+            engine.updateRunProgress(runId, {
+              currentPhase: 'model',
+              currentStep: 'model:no_progress_wrapup',
+              currentTool: null,
+              currentStepStartedAt: isoNow(),
+            });
+            let wrapTokens = 0;
+            try {
+              const wrapResponse = await withModelCallTimeout(
+                provider.chat(
+                  sanitizeConversationMessages([
+                    ...messages,
+                    {
+                      role: 'system',
+                      content: buildNoProgressWrapupPrompt({
+                        readOnlyCount,
+                        alreadyRead,
+                        platform: options?.source || null,
+                      }),
+                    },
+                  ]),
+                  [],
+                  { model, reasoningEffort: engine.getReasoningEffort(providerName, options) },
+                ),
+                options,
+                'No-progress wrap-up',
+              );
+              wrapTokens = wrapResponse.usage?.totalTokens || 0;
+              lastContent = sanitizeModelOutput(wrapResponse.content || '', { model });
+            } catch (wrapErr) {
+              console.warn(`[Run ${shortenRunId(runId)}] no_progress_wrapup failed: ${summarizeForLog(wrapErr?.message || wrapErr, 180)}`);
+            }
+            totalTokens += wrapTokens;
+            const usableWrap = normalizeOutgoingMessage(lastContent, options?.source || null);
+            if (!usableWrap) {
+              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, usableWrap ? wrapTokens : 0);
+            }
+            engine.recordRunEvent(userId, runId, 'no_progress_wrapup_delivered', {
+              iteration,
+              readOnlyCount,
+              source: usableWrap ? 'model' : 'deterministic',
+              forceWrapupSource,
+              stepIndex,
+            }, { agentId });
+            // This wrap-up is a forced, tool-less terminal answer: the model had no
+            // way to call send_message itself. On automatic background runs the plain
+            // result is normally gated, which would silently drop this. Mark it so the
+            // task runtime delivers it — a stuck/blocked scheduled task must still
+            // surface its result instead of going silent.
+            if (
+              (triggerSource === 'schedule' || triggerSource === 'tasks')
+              && options.deliveryState
+              && !engine.activeRuns.get(runId)?.messagingSent
+            ) {
+              options.deliveryState.terminalWrapup = true;
+            }
+            directAnswerEligible = true;
+            break;
+          }
         }
       }
 
@@ -1410,6 +1591,22 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           lastContent = '';
           continue;
         }
+        if (shouldContinueAfterRecoverableToolFailure({
+          lastContent,
+          remainingIterations: iterationBudget.remaining,
+          toolExecutions,
+        })) {
+          engine.recordRunEvent(userId, runId, 'recoverable_tool_failure_continued', {
+            iteration,
+            remainingIterations: iterationBudget.remaining,
+          }, { agentId });
+          messages.push({
+            role: 'system',
+            content: buildRecoverableToolFailureGuidance(toolExecutions),
+          });
+          lastContent = '';
+          continue;
+        }
         const loopDecision = await engine.decideLoopState({
           provider,
           providerName,
@@ -1908,6 +2105,9 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         if (runMeta?.terminalInterim) {
           break;
         }
+        if (isDeliveryTerminated(runMeta, options.deliveryState)) {
+          break;
+        }
       }
 
       // Update analysis-paralysis counter after each iteration's tool calls.
@@ -1924,6 +2124,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
 
       if (engine.isRunStopped(runId)) break;
       if (engine.getRunMeta(runId)?.terminalInterim) break;
+      if (isDeliveryTerminated(engine.getRunMeta(runId), options.deliveryState)) break;
       if (engine.getRunMeta(runId)?.widgetSnapshotSaved) break;
       if (!engine.activeRuns.has(runId)) break;
     }
@@ -1974,6 +2175,12 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       lastContent = 'Widget snapshot updated.';
     }
     const messagingSent = runMeta?.messagingSent || false;
+    const stagedProactiveReply = normalizeOutgoingMessage(
+      runMeta?.stagedProactiveMessage?.content
+      || options?.deliveryState?.stagedProactiveMessage?.content
+      || '',
+      options?.source || null,
+    );
     const lastToolWasMessaging = runMeta?.lastToolName === 'send_message' || runMeta?.lastToolName === 'make_call';
 
     // Hermes _handle_max_iterations: if the run exhausted its step budget without a
@@ -2079,6 +2286,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     if (
       !normalizeOutgoingMessage(lastContent, options?.source || null)
       && !messagingSent
+      && !stagedProactiveReply
       && runMeta?.widgetSnapshotSaved !== true
     ) {
       const explicitNoResponse = (
@@ -2128,10 +2336,11 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     const normalizedLastContent = normalizeOutgoingMessage(lastContent, options?.source || null);
     let finalResponseText = messagingSent
       ? (sentMessageText || (normalizedLastContent ? lastContent.trim() : ''))
-      : (normalizedLastContent ? lastContent.trim() : sentMessageText);
+      : (normalizedLastContent ? lastContent.trim() : (stagedProactiveReply || sentMessageText));
     const lastFinalDeliveryMessage = normalizeOutgoingMessage(
       runMeta?.lastSentMessage
       || (Array.isArray(runMeta?.sentMessages) ? runMeta.sentMessages[runMeta.sentMessages.length - 1] : '')
+      || runMeta?.stagedProactiveMessage?.content
       || '',
       options?.source || null
     );
@@ -2469,7 +2678,12 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     }
 
     throw err;
+  } finally {
+    releaseReservation();
   }
 }
 
-module.exports = { runConversation };
+module.exports = {
+  getFailureFallbackModelId,
+  runConversation,
+};

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

@@ -1,8 +1,8 @@
 'use strict';
 
 const FIRST_UPDATE_MS = 30 * 1000;
-const REPEAT_UPDATE_MS = 75 * 1000;
-const STALL_MS = 150 * 1000;
+const REPEAT_UPDATE_MS = 120 * 1000;
+const STALL_MS = 240 * 1000;
 const TICK_MS = 15 * 1000;
 
 function isoNow() {
@@ -60,13 +60,13 @@ function evaluateProgressLiveness(runMeta, now = Date.now()) {
 
 function buildProgressNudge({ stalled = false } = {}) {
   return [
-    'Mandatory internal progress check for the active messaging run.',
+    'Internal progress check for the active messaging run.',
     stalled
       ? 'No verified progress has been recorded for the stall threshold.'
       : 'The originating chat has not received a user-visible update for the progress threshold.',
-    'Before starting more tool work, either send a concise model-authored interim update with send_interim_update, report a real blocker, or finish with the final answer.',
-    'Do not continue silently once this check is present unless the immediate next action itself delivers a final answer or explicit no-response decision.',
-    'Do not repeat previous status text and do not treat an interim update as final delivery.',
+    'Before starting more tool work, decide whether the user has a materially useful new status, a real blocker, a final answer, or no user-visible update is needed.',
+    'Only send_interim_update when there is new user-relevant progress or a blocker. Continue silently if nothing materially changed.',
+    'Never expose this progress check, internal state, or tool bookkeeping to the user, and do not treat an interim update as final delivery.',
   ].join(' ');
 }
 

package/server/services/ai/loopPolicy.js

@@ -1,59 +1,39 @@
-/**
- * loopPolicy.js
- *
- * Single source of truth for every tunable limit in the agent loop.
- * No magic numbers live in engine.js — everything flows from here.
- *
- * Values resolve in priority order:
- *   1. Per-run option override (options.*)
- *   2. Agent AI settings (aiSettings.*)
- *   3. Hardcoded sane default
- *
- * "Open but stable": limits exist as safety nets, not as the primary
- * exit signal. The AI signals completion via task_complete; these
- * numbers only fire when something goes wrong.
- */
-
-// The iteration count is intentionally NOT a real limit: the agent runs until it
-// signals completion (task_complete / judged terminal), an external blocker, or a
-// genuine stuck-state guard fires (consecutive tool failures, repetition guard,
-// model-failure recoveries). This number only exists so arithmetic/logging have a
-// finite sentinel; it is set far above any real task length so it never cuts a run.
-const UNLIMITED_ITERATIONS = 1_000_000;
-
-const DEFAULT_MAX_ITERATIONS = UNLIMITED_ITERATIONS;
-const DEFAULT_WIDGET_MAX_ITERATIONS = UNLIMITED_ITERATIONS;
-const DEFAULT_PLAN_EXECUTE_MAX_ITERATIONS = UNLIMITED_ITERATIONS;
+// Limits resolve in priority order: per-run options → agent AI settings → hardcoded defaults.
+// They are safety nets only; task_complete / progress guards are the real exit signals.
+
+// The iteration ceiling is a pure runaway safety net, NOT the primary stop signal.
+// A run stops when it makes no real progress (consecutiveReadOnlyIterations cap,
+// which resets the moment the agent does anything state-changing), or when the
+// repetition / tool-failure / model-recovery guards fire, or when the model signals
+// task_complete. These ceilings are set high so they only ever catch a genuine
+// runaway and never guillotine a long, legitimately-progressing complex task.
+const DEFAULT_MAX_ITERATIONS = 250;
+const DEFAULT_WIDGET_MAX_ITERATIONS = 150;
+const DEFAULT_PLAN_EXECUTE_MAX_ITERATIONS = 250;
 // Less aggressive than 0.60 so the model retains file contents it already read for
 // longer, instead of losing them to compaction and re-reading the same files.
 const DEFAULT_COMPACTION_THRESHOLD = 0.80;
+// The real "stop when stuck" guard. Counts consecutive turns of pure reading/
+// searching/inspecting with zero state change; resets to 0 on any concrete progress.
+const DEFAULT_MAX_CONSECUTIVE_READ_ONLY_ITERATIONS = 8;
 const DEFAULT_MAX_CONSECUTIVE_TOOL_FAILURES = 5;
 const DEFAULT_MAX_MODEL_FAILURE_RECOVERIES = 3;
 
-// Hard ceiling — only guards against absurd/overflow config values, not task length.
-const MAX_ALLOWED_ITERATIONS = UNLIMITED_ITERATIONS;
+const MAX_ALLOWED_ITERATIONS = 400;
+const MAX_ALLOWED_READ_ONLY_ITERATIONS = 25;
 const MAX_ALLOWED_TOOL_FAILURES = 50;
 const MAX_ALLOWED_MODEL_RECOVERIES = 10;
 const MAX_ALLOWED_BUDGET_CHARS = 500_000;
 
-/** Return n if finite and positive, otherwise fallback. */
 function finitePositive(n, fallback) {
   return Number.isFinite(n) && n > 0 ? n : fallback;
 }
 
-/** Clamp n to [lo, hi]; return fallback if not finite. */
 function clampFinite(n, lo, hi, fallback) {
   if (!Number.isFinite(n)) return fallback;
   return Math.min(Math.max(n, lo), hi);
 }
 
-/**
- * @param {object} aiSettings   - from getAiSettings()
- * @param {string} triggerType  - 'chat' | 'schedule' | 'subagent' | etc.
- * @param {string} analysisMode - 'direct_answer' | 'execute' | 'plan_execute'
- * @param {object} options      - per-run options (may override anything)
- * @returns {LoopPolicy}
- */
 function buildLoopPolicy(aiSettings = {}, triggerType = 'chat', analysisMode = 'execute', options = {}) {
   const autonomyPolicy = options.autonomyPolicy && typeof options.autonomyPolicy === 'object'
     ? options.autonomyPolicy
@@ -112,6 +92,16 @@ function buildLoopPolicy(aiSettings = {}, triggerType = 'chat', analysisMode = '
     DEFAULT_MAX_MODEL_FAILURE_RECOVERIES,
   );
 
+  const rawReadOnlyIterations = options.maxConsecutiveReadOnlyIterations != null
+    ? Number(options.maxConsecutiveReadOnlyIterations)
+    : Number(aiSettings.max_consecutive_read_only_iterations);
+  const maxConsecutiveReadOnlyIterations = clampFinite(
+    Math.floor(rawReadOnlyIterations),
+    3,
+    MAX_ALLOWED_READ_ONLY_ITERATIONS,
+    DEFAULT_MAX_CONSECUTIVE_READ_ONLY_ITERATIONS,
+  );
+
   // compactionThreshold must be in (0, 1]; clamp to [0.1, 1].
   const compactionThreshold = clampFinite(
     Number(aiSettings.compaction_threshold),
@@ -122,6 +112,7 @@ function buildLoopPolicy(aiSettings = {}, triggerType = 'chat', analysisMode = '
 
   return {
     maxIterations,
+    maxConsecutiveReadOnlyIterations,
     maxConsecutiveToolFailures,
     maxModelFailureRecoveries,
 
@@ -142,9 +133,6 @@ function buildLoopPolicy(aiSettings = {}, triggerType = 'chat', analysisMode = '
   };
 }
 
-/**
- * Map a tool name to its result-size category.
- */
 function getToolCategory(toolName) {
   if (!toolName) return 'default';
   if (/^(read_file|write_file|search_files|list_directory|file_)/.test(toolName)) return 'file';
@@ -153,9 +141,6 @@ function getToolCategory(toolName) {
   return 'default';
 }
 
-/**
- * Resolve soft + hard limits for a specific tool from the policy.
- */
 function resolveToolResultLimits(toolName, policy) {
   const category = getToolCategory(toolName);
   const soft = policy.toolResultBudget[category] ?? policy.toolResultBudget.default;
@@ -163,4 +148,12 @@ function resolveToolResultLimits(toolName, policy) {
   return { softLimit: soft, hardLimit: hard };
 }
 
-module.exports = { buildLoopPolicy, getToolCategory, resolveToolResultLimits };
+function resolveChurnNudgeThreshold(goalContract) {
+  const complexity = String(goalContract?.complexity || 'standard').toLowerCase();
+  const autonomyLevel = String(goalContract?.autonomyLevel || goalContract?.autonomy_level || 'normal').toLowerCase();
+  if (complexity === 'simple') return 2;
+  if (complexity === 'complex' || autonomyLevel === 'high') return 5;
+  return 3;
+}
+
+module.exports = { buildLoopPolicy, getToolCategory, resolveToolResultLimits, resolveChurnNudgeThreshold };