neoagent 3.2.1-beta.0 → 3.2.1-beta.10

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

@@ -55,6 +55,16 @@ const { normalizeCompletionConfidence, shouldAcceptTaskComplete } = require('../
 const { enforceRateLimits } = require('../rate_limits');
 const { ToolRepetitionGuard } = require('../repetitionGuard');
 const { shortenRunId, summarizeForLog } = require('../logFormat');
+const {
+  normalizeModelSelections,
+  resolveModelSelection,
+} = require('../model_identity');
+const {
+  isModelCoolingDown,
+  recordModelFailure,
+  recordModelSuccess,
+} = require('../model_failure_cache');
+const { getProviderForUser } = require('../provider_selector');
 const { IterationBudget } = require('./iteration_budget');
 const {
   buildBlankAfterToolFailureGuidance,
@@ -116,7 +126,7 @@ const {
 const {
   requestModelResponse: requestModelResponseImpl,
   requestStructuredJson: requestStructuredJsonImpl,
-  withModelCallTimeout,
+  runAbortableModelCall,
 } = require('./model_io');
 const {
   publishInterimUpdate: publishInterimUpdateImpl,
@@ -144,6 +154,7 @@ const {
   buildModelFailureLoopPrompt,
 } = require('../messagingFallback');
 const {
+  assessResearchAdequacy,
   classifyToolExecution,
   gatheredNewEvidence,
   isSubstantiveProgressToolName,
@@ -164,6 +175,7 @@ const {
   normalizeRetrievalPlan,
   shouldEnhanceRetrieval,
 } = require('../../memory/retrieval_reasoning');
+const { isAbortError, throwIfAborted } = require('../../../utils/abort');
 
 function generateTitle(task) {
   if (!task || typeof task !== 'string') return 'Untitled';
@@ -291,13 +303,34 @@ function summarizeReadTargets(toolExecutions = []) {
   return targets.join('; ');
 }
 
-function buildNoProgressWrapupPrompt({ readOnlyCount = 0, alreadyRead = '', platform = null } = {}) {
+function buildNoProgressWrapupPrompt({
+  readOnlyCount = 0,
+  alreadyRead = '',
+  platform = null,
+  researchAdequacy = null,
+} = {}) {
+  const adequacy = researchAdequacy && typeof researchAdequacy === 'object'
+    ? researchAdequacy
+    : null;
+  const researchIncomplete = adequacy
+    && adequacy.adequate === false
+    && adequacy.intensity
+    && adequacy.intensity !== 'none';
   return [
     `This is the final turn for this run (no further tool calls; ${Math.max(0, Number(readOnlyCount) || 0)} read-only turns without a state change).`,
     alreadyRead ? `Already gathered: ${alreadyRead}.` : '',
+    researchIncomplete
+      ? `Research coverage is incomplete: ${adequacy.reason || 'requested targets still lack primary evidence.'}`
+      : '',
+    researchIncomplete && adequacy.uncoveredTargets?.length
+      ? `Uncovered research targets: ${adequacy.uncoveredTargets.join('; ')}.`
+      : '',
     'Write the answer now from everything you have already gathered in this conversation. Deliver the useful result you DO have — calendar, weather, emails, search findings, whatever was collected — formatted as the actual answer to the original request.',
     'If one part could not be retrieved, still deliver everything else and note the missing part in at most one short clause. Never withhold a useful answer because a single detail is missing.',
-    'Only report a pure blocker if you genuinely gathered nothing usable at all. Do not describe the result as unfinished, unconfirmed, "blocked", or "still working" when you have something useful — this IS the final answer.',
+    'Do not invent entities, products, people, files, outcomes, or next-step work that is not already supported by tool evidence in this conversation.',
+    researchIncomplete
+      ? 'Because research is incomplete, clearly label assumptions and missing targets. Prefer a partial verified answer or a concrete blocker over a confident fabricated comparison.'
+      : 'Only report a pure blocker if you genuinely gathered nothing usable at all. Do not describe the result as unfinished, unconfirmed, "blocked", or "still working" when you have something useful — this IS the final answer.',
     buildMaxIterationWrapupPrompt(platform),
   ].filter(Boolean).join('\n\n');
 }
@@ -403,145 +436,75 @@ function buildAutonomyPolicyFromAnalysis(analysis = {}) {
   };
 }
 
-async function getProviderForUser(userId, task = '', isSubagent = false, modelOverride = null, providerConfig = {}) {
-  const { getSupportedModels, createProviderInstance } = require('../models');
-  const agentId = providerConfig.agentId || null;
-  const aiSettings = getAiSettings(userId, agentId);
-  const models = await getSupportedModels(userId, agentId);
-
-  let enabledIds = Array.isArray(aiSettings.enabled_models) ? aiSettings.enabled_models : [];
-  const defaultChatModel = aiSettings.default_chat_model || 'auto';
-  const defaultSubagentModel = aiSettings.default_subagent_model || 'auto';
-  const smarterSelection = aiSettings.smarter_model_selector !== false && aiSettings.smarter_model_selector !== 'false';
-
-  const knownModelIds = new Set(models.map((m) => m.id));
-  const selectableModels = models.filter((m) => m.available !== false);
-
-  enabledIds = Array.isArray(enabledIds)
-    ? enabledIds
-      .map((id) => String(id))
-      .filter((id) => knownModelIds.has(id))
-    : [];
-
-  let availableModels = selectableModels.filter((m) => enabledIds.includes(m.id));
-  if (availableModels.length === 0) {
-    enabledIds = selectableModels.map((m) => m.id);
-    availableModels = [...selectableModels];
-  }
-
-  const fallbackModel = availableModels.length > 0 ? availableModels[0] : selectableModels[0];
-
-  if (!fallbackModel) {
-    throw new Error('No AI providers are currently available. Open Settings and configure at least one provider.');
-  }
-
-  let selectedModelDef = fallbackModel;
-  const userSelectedDefault = isSubagent ? defaultSubagentModel : defaultChatModel;
-
-  if (modelOverride && typeof modelOverride === 'string') {
-    const requested = models.find((m) => m.id === modelOverride.trim());
-    // An explicit override (e.g. a failure fallback picked by getFailureFallbackModelId)
-    // may intentionally sit outside the user's enabled_models pool — that's the whole
-    // point when no in-pool cross-provider option exists. Only require availability.
-    if (requested && requested.available !== false) {
-      selectedModelDef = requested;
-      return {
-        provider: createProviderInstance(selectedModelDef.provider, userId, providerConfig),
-        model: selectedModelDef.id,
-        providerName: selectedModelDef.provider
-      };
-    }
-  }
-
-  if (userSelectedDefault && userSelectedDefault !== 'auto') {
-    selectedModelDef = models.find((m) => m.id === userSelectedDefault) || fallbackModel;
-  } else {
-    const selectionHint = providerConfig.selectionHint && typeof providerConfig.selectionHint === 'object'
-      ? providerConfig.selectionHint
-      : {};
-    const preferredPurpose = String(selectionHint.purpose || '').trim().toLowerCase();
-    const highAutonomy = selectionHint.autonomyLevel === 'high' || selectionHint.complexity === 'complex';
-    const requiredConfidence = String(selectionHint.requiredConfidence || '').trim().toLowerCase();
-    const costMode = String(selectionHint.costMode || aiSettings.cost_mode || 'balanced_auto').trim().toLowerCase();
-    const requestedPurpose = ['planning', 'coding', 'general', 'fast'].includes(preferredPurpose)
-      ? preferredPurpose
-      : '';
-    const priceRank = { free: 0, cheap: 1, medium: 2, expensive: 3 };
-    const chooseForPurpose = (purpose) => {
-      const candidates = availableModels.filter((model) => model.purpose === purpose);
-      if (candidates.length === 0) return null;
-      if (['economy', 'cost_saver', 'lowest_cost'].includes(costMode)) {
-        return [...candidates].sort((left, right) => (
-          (priceRank[left.priceTier] ?? 99) - (priceRank[right.priceTier] ?? 99)
-        ))[0];
-      }
-      if (['quality', 'highest_quality'].includes(costMode) || requiredConfidence === 'high') {
-        return candidates.find((model) => model.priceTier !== 'free' && model.priceTier !== 'cheap') || candidates[0];
-      }
-      return candidates[0];
-    };
-
-    if (smarterSelection && requestedPurpose) {
-      selectedModelDef = chooseForPurpose(requestedPurpose) || fallbackModel;
-    } else if (smarterSelection && highAutonomy) {
-      selectedModelDef = chooseForPurpose('planning') || chooseForPurpose('general') || fallbackModel;
-    } else if (isSubagent) {
-      selectedModelDef = chooseForPurpose('fast') || fallbackModel;
-    } else {
-      selectedModelDef = chooseForPurpose('general') || fallbackModel;
-    }
-  }
-
-  return {
-    provider: createProviderInstance(selectedModelDef.provider, userId, providerConfig),
-    model: selectedModelDef.id,
-    providerName: selectedModelDef.provider
-  };
-}
-
-async function getFailureFallbackModelId(userId, agentId, currentModelId, preferredFallbackId = null, failureError = null) {
+async function getFailureFallbackModelId(
+  userId,
+  agentId,
+  currentModelId,
+  preferredFallbackId = null,
+  failureError = null,
+  signal = null,
+  excludedModelIds = [],
+) {
   const { getSupportedModels } = require('../models');
   const aiSettings = getAiSettings(userId, agentId);
-  const models = await getSupportedModels(userId, agentId);
-  const availableModels = models.filter((model) => model.available !== false);
-  const knownIds = new Set(availableModels.map((model) => model.id));
-  const enabledIds = Array.isArray(aiSettings.enabled_models)
-    ? aiSettings.enabled_models.map((id) => String(id)).filter((id) => knownIds.has(id))
+  const models = await getSupportedModels(userId, agentId, { signal });
+  const excluded = new Set(
+    [...excludedModelIds]
+      .map((id) => String(id || '').trim())
+      .filter(Boolean),
+  );
+  const availableModels = models.filter(
+    (model) => model.available !== false
+      && !isModelCoolingDown(userId, agentId, model.id)
+      && !excluded.has(model.id),
+  );
+  const configuredEnabledIds = Array.isArray(aiSettings.enabled_models)
+    ? aiSettings.enabled_models.map((id) => String(id).trim()).filter(Boolean)
     : [];
-  const pool = enabledIds.length > 0
+  const enabledIds = normalizeModelSelections(availableModels, configuredEnabledIds);
+  const pool = configuredEnabledIds.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;
-
-  // When the failure is a provider-level rate limit, the preferred fallback is
-  // likely on the same provider and will hit the same limit. Skip it and prefer
-  // a fallback from a different provider instead.
-  const isProviderRateLimit = /429|rate.?limit|free-models-per/i.test(String(failureError?.message || ''));
-
-  if (preferredFallbackId && preferredFallbackId !== currentModelId && !isProviderRateLimit) {
-    const preferred = fallbackSearchPool.find((model) => model.id === preferredFallbackId)
-      || availableModels.find((model) => model.id === preferredFallbackId);
-    if (preferred) return preferred.id;
+  const fallbackSearchPool = pool;
+  const currentModel = resolveModelSelection(models, currentModelId);
+
+  // Provider-wide failures (credentials, throttling, or service outages) are
+  // likely to affect another model on the same provider. Prefer a different
+  // provider before consulting the configured fallback.
+  const failureStatus = Number(
+    failureError?.status
+    ?? failureError?.statusCode
+    ?? failureError?.response?.status,
+  );
+  const isProviderScopedFailure = (
+    failureStatus === 401
+    || failureStatus === 403
+    || failureStatus === 429
+    || (failureStatus >= 500 && failureStatus < 600)
+    || /rate.?limit|free-models-per|service unavailable|provider unavailable|authentication|api key/i
+      .test(String(failureError?.message || ''))
+  );
+
+  if (preferredFallbackId && !isProviderScopedFailure) {
+    const preferred = resolveModelSelection(fallbackSearchPool, preferredFallbackId)
+      || resolveModelSelection(availableModels, preferredFallbackId);
+    if (preferred && preferred.id !== currentModel?.id) return preferred.id;
   }
 
   if (currentModel?.provider) {
     const differentProvider = fallbackSearchPool.find((model) =>
-      model.id !== currentModelId && model.provider !== currentModel.provider);
+      model.id !== currentModel.id && 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 = fallbackSearchPool.find((model) => model.id === preferredFallbackId)
-      || availableModels.find((model) => model.id === preferredFallbackId);
-    if (preferred) return preferred.id;
+  // If no different-provider model exists, still try the preferred fallback.
+  if (preferredFallbackId) {
+    const preferred = resolveModelSelection(fallbackSearchPool, preferredFallbackId)
+      || resolveModelSelection(availableModels, preferredFallbackId);
+    if (preferred && preferred.id !== currentModel?.id) return preferred.id;
   }
 
-  const differentModel = fallbackSearchPool.find((model) => model.id !== currentModelId);
+  const differentModel = fallbackSearchPool.find((model) => model.id !== currentModel?.id);
   return differentModel?.id || null;
 }
 
@@ -552,6 +515,7 @@ function estimateTokenValue(value) {
 }
 
 async function runConversation(engine, userId, userMessage, options = {}, _modelOverride = null) {
+  throwIfAborted(options.signal, 'Agent run aborted before startup.');
   const triggerType = options.triggerType || 'user';
   const { resolveAgentId } = require('../../agents/manager');
   const agentId = resolveAgentId(userId, options.agentId || options.agent_id || null);
@@ -563,7 +527,9 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
   const triggerSource = options.triggerSource || 'web';
   let provider = null;
   let model = null;
+  let modelSelectionId = null;
   let providerName = null;
+  const modelTurnFailedModelSelectionIds = new Set();
   let messages = [];
   let iteration = 0;
   let totalTokens = 0;
@@ -572,7 +538,9 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
   let failedStepCount = 0;
   let toolExecutions = [];
   let deliverableWorkflow = null;
-  let runTitle;
+  let detachExternalAbort = null;
+  const runTitle = generateTitle(userMessage);
+  let runRecordCreated = false;
   const timelineService = app?.locals?.timelineService || null;
 
   const { releaseReservation } = enforceRateLimits(userId, {
@@ -589,6 +557,59 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
   // analysis when the mode is known. See the post-analysis policy rebuild below.
   let loopPolicy = buildLoopPolicy(aiSettings, triggerType, 'execute', options);
   let maxIterations = loopPolicy.maxIterations;
+  const initialRunMetadata = buildInitialRunMetadata(options);
+  const requestedModel = String(
+    _modelOverride
+    || (triggerType === 'subagent' ? aiSettings.default_subagent_model : aiSettings.default_chat_model)
+    || 'auto',
+  ).trim();
+  try {
+    db.prepare(`INSERT INTO agent_runs(
+      id, user_id, agent_id, title, status, trigger_type, trigger_source, model, metadata_json
+    ) VALUES(?, ?, ?, ?, 'running', ?, ?, ?, ?)`).run(
+      runId,
+      userId,
+      agentId,
+      runTitle,
+      triggerType,
+      triggerSource,
+      requestedModel,
+      Object.keys(initialRunMetadata).length ? JSON.stringify(initialRunMetadata) : null,
+    );
+    runRecordCreated = true;
+  } catch (error) {
+    if (/unique|primary key|constraint/i.test(String(error?.message || ''))) {
+      const conflict = new Error(`A run with id "${runId}" already exists.`);
+      conflict.code = 'RUN_ID_CONFLICT';
+      throw conflict;
+    }
+    throw error;
+  }
+  const startupAbortController = new AbortController();
+  engine.activeRuns.set(runId, {
+    userId,
+    agentId,
+    title: runTitle,
+    status: 'running',
+    aborted: false,
+    abortController: startupAbortController,
+    pauseAvailable: false,
+    toolPids: new Set(),
+    subagentDepth: Math.max(0, Number(options.subagentDepth) || 0),
+  });
+  if (options.signal) {
+    const abortFromExternal = () => {
+      engine.interruptRun(
+        runId,
+        String(options.signal.reason || 'Agent run interrupted by its caller.'),
+      );
+    };
+    if (options.signal.aborted) abortFromExternal();
+    else options.signal.addEventListener('abort', abortFromExternal, { once: true });
+    detachExternalAbort = () => {
+      options.signal.removeEventListener('abort', abortFromExternal);
+    };
+  }
   const providerStatusConfig = {
     agentId,
     onStatus: (status) => {
@@ -605,18 +626,61 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     userMessage,
     triggerType === 'subagent',
     _modelOverride,
-    providerStatusConfig
+    { ...providerStatusConfig, signal: startupAbortController.signal }
   );
   provider = selectedProvider.provider;
   model = selectedProvider.model;
+  modelSelectionId = selectedProvider.modelSelectionId;
   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;
-    console.log(`[Engine] ${phase} failed on ${failedModel}; attempting fallback to: ${fallbackModelId}`);
+  if (
+    startupAbortController.signal.aborted
+    || engine.getRunMeta(runId)?.status !== 'running'
+  ) {
+    const startupError = new Error(
+      String(startupAbortController.signal.reason || 'Run stopped during model selection.'),
+    );
+    startupError.name = 'AbortError';
+    startupError.code = 'ABORT_ERR';
+    throw startupError;
+  }
+  db.prepare('UPDATE agent_runs SET model = ?, updated_at = datetime(\'now\') WHERE id = ?')
+    .run(modelSelectionId, runId);
+  const recordFailedModel = (failedSelectionId, error, excludedModels) => {
+    excludedModels.add(failedSelectionId);
+    recordModelFailure(userId, agentId, failedSelectionId, error);
+  };
+  const switchToFallbackModel = async (
+    failedSelectionId,
+    error,
+    phase,
+    excludedModels,
+  ) => {
+    recordFailedModel(failedSelectionId, error, excludedModels);
+    const fallbackModelId = await getFailureFallbackModelId(
+      userId,
+      agentId,
+      failedSelectionId,
+      aiSettings.fallback_model_id,
+      error,
+      engine.getRunMeta(runId)?.abortController?.signal,
+      excludedModels,
+    );
+    if (!fallbackModelId || fallbackModelId === failedSelectionId) return false;
+    const failureSummary = summarizeForLog(error?.message || error, 180);
+    console.log(
+      `[Engine] ${phase} failed on ${failedSelectionId}: ${failureSummary}; attempting fallback to: ${fallbackModelId}`
+    );
+    engine.recordRunEvent(userId, runId, 'model_fallback', {
+      phase,
+      failedModel: failedSelectionId,
+      fallbackModel: fallbackModelId,
+      errorCode: error?.code || null,
+      errorStatus: error?.status || error?.statusCode || error?.response?.status || null,
+      error: failureSummary,
+    }, { agentId });
     engine.emit(userId, 'run:interim', {
       runId,
-      message: `Model service failed on ${failedModel}; retrying with ${fallbackModelId}.`,
+      message: `Model service failed on ${failedSelectionId}; retrying with ${fallbackModelId}.`,
       phase: 'model_fallback'
     });
     const fallback = await getProviderForUser(
@@ -624,46 +688,50 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       userMessage,
       triggerType === 'subagent',
       fallbackModelId,
-      providerStatusConfig
+      {
+        ...providerStatusConfig,
+        signal: engine.getRunMeta(runId)?.abortController?.signal,
+      }
     );
     provider = fallback.provider;
     model = fallback.model;
+    modelSelectionId = fallback.modelSelectionId;
     providerName = fallback.providerName;
+    db.prepare('UPDATE agent_runs SET model = ?, updated_at = datetime(\'now\') WHERE id = ?')
+      .run(modelSelectionId, runId);
+    Object.assign(engine.getRunMeta(runId) || {}, {
+      model,
+      modelSelectionId,
+      providerName,
+    });
     return true;
   };
   const runWithModelFallback = async (phase, fn) => {
-    try {
-      return await fn();
-    } catch (err) {
-      const failedModel = model;
-      const switched = await switchToFallbackModel(failedModel, err, phase);
-      if (!switched) throw err;
-      return await fn();
+    let recoveries = 0;
+    const failedModels = new Set();
+    while (true) {
+      try {
+        const result = await fn();
+        recordModelSuccess(userId, agentId, modelSelectionId);
+        return result;
+      } catch (err) {
+        if (recoveries >= loopPolicy.maxModelFailureRecoveries) {
+          recordFailedModel(modelSelectionId, err, failedModels);
+          throw err;
+        }
+        const failedSelectionId = modelSelectionId;
+        const switched = await switchToFallbackModel(
+          failedSelectionId,
+          err,
+          phase,
+          failedModels,
+        );
+        if (!switched) throw err;
+        recoveries += 1;
+      }
     }
   };
 
-  runTitle = generateTitle(userMessage);
-  const initialRunMetadata = buildInitialRunMetadata(options);
-  db.prepare(`INSERT INTO agent_runs(
-    id, user_id, agent_id, title, status, trigger_type, trigger_source, model, metadata_json
-  ) 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,
-    runTitle,
-    triggerType,
-    triggerSource,
-    model,
-    Object.keys(initialRunMetadata).length ? JSON.stringify(initialRunMetadata) : null,
-  );
-
   const retryMessagingState = options.messagingRetryState || {};
   const carriedFinalMessage = String(retryMessagingState.lastFinalMessage || '').trim();
   const carriedExplicitMessageSent = retryMessagingState.explicitMessageSent === true;
@@ -685,6 +753,9 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     userId,
     agentId,
     title: runTitle,
+    model,
+    modelSelectionId,
+    providerName,
     status: 'running',
     aborted: false,
     messagingSent: false,
@@ -709,6 +780,8 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     voiceSessionId: options.voiceSessionId || null,
     steeringQueue: [],
     systemSteeringQueue: [],
+    abortController: startupAbortController,
+    pauseAvailable: false,
     toolPids: new Set(),
     subagentDepth: Math.max(0, Number(options.subagentDepth) || 0),
     repetitionGuard: new ToolRepetitionGuard(),
@@ -733,10 +806,21 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     goalContract: carriedGoalContract,
   });
   engine.startMessagingProgressSupervisor(runId);
-  engine.emit(userId, 'run:start', { runId, agentId, title: runTitle, model, triggerType, triggerSource });
+  engine.emit(userId, 'run:start', {
+    runId,
+    agentId,
+    title: runTitle,
+    model,
+    modelSelectionId,
+    provider: providerName,
+    triggerType,
+    triggerSource,
+  });
   engine.recordRunEvent(userId, runId, 'run_started', {
     title: runTitle,
     model,
+    modelSelectionId,
+    provider: providerName,
     triggerType,
     triggerSource,
   }, { agentId });
@@ -750,7 +834,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     triggerSource,
   });
   console.info(
-    `[Run ${shortenRunId(runId)}] started trigger=${triggerSource} type=${triggerType} model=${model} title=${summarizeForLog(runTitle, 120)}`
+    `[Run ${shortenRunId(runId)}] started trigger=${triggerSource} type=${triggerType} model=${modelSelectionId} title=${summarizeForLog(runTitle, 120)}`
   );
 
   const systemPrompt = await engine.buildSystemPrompt(userId, {
@@ -881,7 +965,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
   if (triggerSource === 'messaging') {
     const runMetaForCompose = engine.getRunMeta(runId);
     if (runMetaForCompose) {
-      runMetaForCompose.composeProgressUpdate = async ({ stalled = false } = {}) => {
+      runMetaForCompose.composeProgressUpdate = async ({ stalled = false, signal = null } = {}) => {
         try {
           const rm = engine.getRunMeta(runId);
           const ledger = rm?.progressLedger || {};
@@ -898,7 +982,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           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.' : '',
+            stalled ? 'No verified progress has occurred for the stall threshold. State that fact plainly if it matters; do not reassure, promise continued work, or imply activity beyond the evidence.' : '',
             '',
             `Original request: ${summarizeForLog(userMessage, 320)}`,
             currentTool ? `Doing now: using ${currentTool}` : '',
@@ -908,17 +992,24 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           // 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(
+            || 'You are the user\'s favorite contact: warm, direct, and competent.';
+          const resp = await runAbortableModelCall(
+            (signal) => provider.chat(
               [
                 { role: 'system', content: sysContent },
                 { role: 'user', content: contextBlock },
               ],
               [],
-              { model, reasoningEffort: engine.getReasoningEffort(providerName, options) },
+              {
+                model,
+                reasoningEffort: engine.getReasoningEffort(providerName, options),
+                signal,
+              },
             ),
-            options,
+            {
+              ...options,
+              signals: [rm?.abortController?.signal, signal],
+            },
             'Progress update compose',
           );
           return sanitizeModelOutput(resp.content || '', { model });
@@ -1029,6 +1120,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           null,
           {
             ...providerStatusConfig,
+            signal: engine.getRunMeta(runId)?.abortController?.signal,
             selectionHint: {
               purpose: requestedPurpose,
               complexity: analysis?.complexity,
@@ -1038,15 +1130,21 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
             },
           }
         );
-        if (selectedAfterAnalysis.model !== model) {
+        if (selectedAfterAnalysis.modelSelectionId !== modelSelectionId) {
           provider = selectedAfterAnalysis.provider;
           model = selectedAfterAnalysis.model;
+          modelSelectionId = selectedAfterAnalysis.modelSelectionId;
           providerName = selectedAfterAnalysis.providerName;
           db.prepare('UPDATE agent_runs SET model = ?, updated_at = datetime(\'now\') WHERE id = ?')
-            .run(model, runId);
+            .run(modelSelectionId, runId);
+          Object.assign(engine.getRunMeta(runId) || {}, {
+            model,
+            modelSelectionId,
+            providerName,
+          });
           engine.emit(userId, 'run:interim', {
             runId,
-            message: `Switched to ${model} for this run after task analysis.`,
+            message: `Switched to ${modelSelectionId} for this run after task analysis.`,
             phase: 'model_selection'
           });
         }
@@ -1207,8 +1305,15 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     // regardless of which iteration they fall in.
     let consecutiveToolFailures = 0;
     const iterationBudget = new IterationBudget(maxIterations);
+    const activeRunMeta = engine.getRunMeta(runId);
+    if (activeRunMeta) activeRunMeta.pauseAvailable = !directAnswerEligible;
 
     while (!directAnswerEligible && iterationBudget.consume()) {
+      const lifecycleAtStart = await engine.checkpointLifecycle(runId, 'iteration_boundary', {
+        iteration: iterationBudget.used,
+        stepIndex,
+      });
+      if (lifecycleAtStart?.action === 'stop' || lifecycleAtStart?.action === 'interrupt') break;
       if (engine.isRunStopped(runId)) break;
       iteration = iterationBudget.used;
 
@@ -1230,7 +1335,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
             reason,
             stoppedBy: hookResult.stopped_by || hookResult.stoppedBy || null,
           }, { agentId });
-          lastContent = reason;
+          engine.stopRun(runId, reason);
           break;
         }
         const systemSteering = String(hookResult?.systemSteering || hookResult?.system_steering || '').trim();
@@ -1289,6 +1394,47 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
               continue;
             }
             alreadyRead = summarizeReadTargets(toolExecutions);
+            const researchAdequacyAtCap = assessResearchAdequacy({
+              analysis,
+              goalContext: runGoalCtx,
+              toolExecutions,
+            });
+            // Incomplete multi-target research is not "stuck" yet if primary sources
+            // remain uncovered. Give one guided research continuation instead of
+            // force-finishing with a guessed comparison.
+            if (
+              researchAdequacyAtCap.adequate === false
+              && researchAdequacyAtCap.intensity !== 'none'
+              && iterMeta
+              && iterMeta.researchAdequacyDeferralUsed !== true
+              && (
+                researchAdequacyAtCap.uncoveredTargets.length > 0
+                || researchAdequacyAtCap.primarySourceCount < researchAdequacyAtCap.requiredPrimarySources
+              )
+            ) {
+              iterMeta.researchAdequacyDeferralUsed = true;
+              iterMeta.consecutiveReadOnlyIterations = Math.max(0, churnNudgeThreshold - 1);
+              messages.push({
+                role: 'system',
+                content: [
+                  'Research self-check: evidence is still incomplete, so this run must not force-finish yet.',
+                  researchAdequacyAtCap.reason ? `Gap: ${researchAdequacyAtCap.reason}` : '',
+                  researchAdequacyAtCap.nextActions?.length
+                    ? `Next safe steps:\n- ${researchAdequacyAtCap.nextActions.join('\n- ')}`
+                    : '',
+                  'Open or fetch primary sources for uncovered targets now. Do not invent the missing comparison from memory or search snippets alone.',
+                ].filter(Boolean).join('\n'),
+              });
+              engine.recordRunEvent(userId, runId, 'read_only_wrapup_deferred_for_research', {
+                iteration,
+                readOnlyCount,
+                intensity: researchAdequacyAtCap.intensity,
+                uncoveredTargets: researchAdequacyAtCap.uncoveredTargets,
+                primarySourceCount: researchAdequacyAtCap.primarySourceCount,
+                requiredPrimarySources: researchAdequacyAtCap.requiredPrimarySources,
+              }, { agentId });
+              continue;
+            }
             triggerForceWrapup = true;
           } else if (readOnlyCount >= churnNudgeThreshold) {
             alreadyRead = summarizeReadTargets(toolExecutions);
@@ -1353,8 +1499,8 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
             });
             let wrapTokens = 0;
             try {
-              const wrapResponse = await withModelCallTimeout(
-                provider.chat(
+              const wrapResponse = await runAbortableModelCall(
+                (signal) => provider.chat(
                   sanitizeConversationMessages([
                     ...messages,
                     {
@@ -1363,13 +1509,22 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
                         readOnlyCount,
                         alreadyRead,
                         platform: options?.source || null,
+                        researchAdequacy: assessResearchAdequacy({
+                          analysis,
+                          goalContext: runGoalCtx,
+                          toolExecutions,
+                        }),
                       }),
                     },
                   ]),
                   [],
-                  { model, reasoningEffort: engine.getReasoningEffort(providerName, options) },
+                  {
+                    model,
+                    reasoningEffort: engine.getReasoningEffort(providerName, options),
+                    signal,
+                  },
                 ),
-                options,
+                { ...options, signal: engine.getRunMeta(runId)?.abortController?.signal },
                 'No-progress wrap-up',
               );
               wrapTokens = wrapResponse.usage?.totalTokens || 0;
@@ -1422,9 +1577,9 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       let metrics = engine.estimatePromptMetrics(messages, tools);
       const contextWindow = provider.getContextWindow(model);
       if (metrics.totalEstimatedTokens > contextWindow * loopPolicy.compactionThreshold) {
-        messages = await withModelCallTimeout(
-          compact(messages, provider, model, contextWindow),
-          options,
+        messages = await runAbortableModelCall(
+          (signal) => compact(messages, provider, model, contextWindow, { signal }),
+          { ...options, signal: engine.getRunMeta(runId)?.abortController?.signal },
           `Context compaction before iteration ${iteration}`,
         );
         messages = sanitizeConversationMessages(messages);
@@ -1444,41 +1599,59 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       let responseModel = model;
       let streamContent = '';
 
-      const tryModelCall = async (retryForFallback = true) => {
-        try {
-          const modelCall = await engine.requestModelResponse({
-            provider,
-            providerName,
-            model,
-            messages,
-            tools,
-            options: { ...options, userId, agentId, runId, phase: 'model_turn' },
-            runId,
-            iteration,
-          });
-          response = modelCall.response;
-          responseModel = modelCall.responseModel;
-          streamContent = modelCall.streamContent;
-        } catch (err) {
-          console.error(`[Engine] Model call failed (${model}):`, err.message);
-          const fallbackModelId = retryForFallback
-            ? await getFailureFallbackModelId(userId, agentId, model, aiSettings.fallback_model_id, err)
-            : null;
-          if (fallbackModelId) {
+      const tryModelCall = async () => {
+        let requestMessages = messages;
+        let requestPhase = 'model_turn';
+        while (true) {
+          try {
+            const modelCall = await engine.requestModelResponse({
+              provider,
+              providerName,
+              model,
+              messages: requestMessages,
+              tools,
+              options: {
+                ...options,
+                userId,
+                agentId,
+                runId,
+                phase: requestPhase,
+                signal: engine.getRunMeta(runId)?.abortController?.signal,
+              },
+              runId,
+              iteration,
+            });
+            response = modelCall.response;
+            responseModel = modelCall.responseModel;
+            streamContent = modelCall.streamContent;
+            recordModelSuccess(userId, agentId, modelSelectionId);
+            return;
+          } catch (err) {
+            console.error(`[Engine] Model call failed (${model}):`, err.message);
+            const runSignal = engine.getRunMeta(runId)?.abortController?.signal;
+            if (isAbortError(err) || runSignal?.aborted) throw err;
+            if (modelFailureRecoveries >= loopPolicy.maxModelFailureRecoveries) {
+              recordFailedModel(
+                modelSelectionId,
+                err,
+                modelTurnFailedModelSelectionIds,
+              );
+              throw err;
+            }
+
             const failedModel = model;
-            console.log(`[Engine] Attempting fallback to: ${fallbackModelId}`);
-            const fallback = await getProviderForUser(
-              userId,
-              userMessage,
-              triggerType === 'subagent',
-              fallbackModelId,
-              providerStatusConfig
+            const switched = await switchToFallbackModel(
+              modelSelectionId,
+              err,
+              'model turn',
+              modelTurnFailedModelSelectionIds,
             );
-            provider = fallback.provider;
-            model = fallback.model;
-            providerName = fallback.providerName;
+            if (!switched) throw err;
 
-            const retryMessages = sanitizeConversationMessages([
+            modelFailureRecoveries += 1;
+            failedStepCount += 1;
+            requestPhase = 'model_turn_fallback';
+            requestMessages = sanitizeConversationMessages([
               ...messages,
               {
                 role: 'system',
@@ -1489,22 +1662,6 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
                 })
               }
             ]);
-
-            const fallbackCall = await engine.requestModelResponse({
-              provider,
-              providerName,
-              model,
-              messages: retryMessages,
-              tools,
-              options: { ...options, userId },
-              runId,
-              iteration,
-            });
-            response = fallbackCall.response;
-            responseModel = fallbackCall.responseModel;
-            streamContent = fallbackCall.streamContent;
-          } else {
-            throw err;
           }
         }
       };
@@ -1512,30 +1669,21 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       try {
         await tryModelCall();
       } catch (err) {
-        const modelError = String(err?.message || 'Model call failed');
-
-        if (modelFailureRecoveries < loopPolicy.maxModelFailureRecoveries) {
-          const failedModel = model;
-          const switched = await switchToFallbackModel(failedModel, err, 'model turn');
-          if (!switched) throw err;
-          modelFailureRecoveries += 1;
-          failedStepCount += 1;
-          messages.push({
-            role: 'system',
-            content: buildModelFailureLoopPrompt({
-              failedModel,
-              nextModel: model,
-              errorMessage: modelError
-            })
-          });
-          engine.emit(userId, 'run:interim', {
-            runId,
-            message: 'Model call failed; adapting and retrying autonomously.',
-            phase: 'recovering'
-          });
+        const lifecycleAbort = err?.name === 'AbortError'
+          || err?.code === 'ABORT_ERR'
+          || /abort/i.test(String(err?.name || ''))
+          || engine.getRunMeta(runId)?.abortController?.signal?.aborted === true;
+        const lifecycleControl = await engine.checkpointLifecycle(runId, 'model_boundary', {
+          iteration,
+          stepIndex,
+        });
+        if (engine.isRunStopped(runId)) break;
+        if (lifecycleAbort && !lifecycleControl && engine.getRunMeta(runId)?.status === 'running') {
+          iterationBudget.refund();
+          iteration = iterationBudget.used;
           continue;
         }
-
+        if (lifecycleControl?.action === 'stop' || lifecycleControl?.action === 'interrupt') break;
         throw err;
       }
 
@@ -1543,6 +1691,12 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         response = { content: streamContent, toolCalls: [], finishReason: 'stop', usage: null };
       }
 
+      const lifecycleAfterModel = await engine.checkpointLifecycle(runId, 'model_boundary', {
+        iteration,
+        stepIndex,
+      });
+      if (lifecycleAfterModel?.action === 'stop' || lifecycleAfterModel?.action === 'interrupt') break;
+
       if (response.usage) {
         totalTokens += response.usage.totalTokens || 0;
       }
@@ -1564,10 +1718,6 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         toolCallCount: response.toolCalls?.length || 0,
         contentPreview: String(lastContent || streamContent || '').slice(0, 240),
       }, { agentId });
-      engine.updateRunProgress(runId, {}, {
-        verified: true,
-      });
-
       const assistantMessage = { role: 'assistant', content: lastContent };
       if (response.toolCalls?.length) assistantMessage.tool_calls = response.toolCalls;
       if (response.providerContentBlocks?.length) assistantMessage.providerContentBlocks = response.providerContentBlocks;
@@ -1677,13 +1827,23 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           iteration,
         }, { agentId });
         if (loopDecision.decision.status === 'continue') {
+          const researchGuidance = loopDecision.researchAdequacy?.adequate === false
+            ? [
+              `Research still incomplete: ${loopDecision.researchAdequacy.reason || 'gather primary evidence for remaining targets.'}`,
+              loopDecision.researchAdequacy.nextActions?.length
+                ? `Next safe steps: ${loopDecision.researchAdequacy.nextActions.join(' ')}`
+                : '',
+            ].filter(Boolean).join(' ')
+            : '';
           messages.push({
             role: 'system',
             content: [
               'The run self-check determined the latest assistant text is not terminal.',
               'Continue with the next safe tool/model step.',
               'If the text was only a progress note, do not repeat it; either make progress or provide a real final/blocker reply.',
-            ].join(' '),
+              'Do not invent missing targets, outcomes, or tool results. Gather evidence or return a truthful partial/blocker answer.',
+              researchGuidance,
+            ].filter(Boolean).join(' '),
           });
           lastContent = '';
           continue;
@@ -1694,7 +1854,10 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
 
       const canRunParallelBatch = (
         response.toolCalls.length > 1
-        && response.toolCalls.every((toolCall) => engine.isReadOnlyToolCall(toolCall))
+        && response.toolCalls.every((toolCall) => engine.isReadOnlyToolCall(
+          toolCall,
+          tools.find((tool) => tool?.name === toolCall?.function?.name) || null,
+        ))
       );
       if (canRunParallelBatch) {
         const parallelToolNames = response.toolCalls
@@ -1718,6 +1881,11 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           iteration,
           options,
         });
+        const lifecycleAfterBatch = await engine.checkpointLifecycle(runId, 'tool_boundary', {
+          iteration,
+          stepIndex: batch.endingStepIndex,
+        });
+        if (lifecycleAfterBatch?.action === 'stop' || lifecycleAfterBatch?.action === 'interrupt') break;
         stepIndex = batch.endingStepIndex;
         let batchGatheredNewEvidence = false;
         for (const item of batch.results) {
@@ -1726,6 +1894,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
             item.toolArgs,
             item.result,
             item.error || '',
+            tools.find((tool) => tool?.name === item.toolName) || null,
           );
           execution.input = item.toolArgs;
           execution.artifacts = await extractArtifactsFromResult(item.toolName, item.result);
@@ -1765,7 +1934,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           currentTool: null,
           currentStepStartedAt: null,
         }, {
-          verified: true,
+          verified: batchGatheredNewEvidence,
         });
         if (analysis.mode === 'execute' || analysis.mode === 'plan_execute') {
           const iterMeta = engine.getRunMeta(runId);
@@ -1922,6 +2091,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
 
         let toolResult;
         let toolErrorMessage = '';
+        let toolInterruptedForPause = false;
         try {
           toolResult = await engine.executeTool(toolName, toolArgs, {
             userId,
@@ -1938,6 +2108,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
             deliveryState: options.deliveryState || null,
             allowMultipleProactiveMessages: options.allowMultipleProactiveMessages === true,
             allowExternalSideEffects: options.allowExternalSideEffects === true,
+            signal: engine.getRunMeta(runId)?.abortController?.signal,
           });
           engine.detachProcessFromRun(runId, toolResult?.pid);
           toolErrorMessage = inferToolFailureMessage(toolName, toolResult);
@@ -1973,17 +2144,30 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
             );
           }
         } catch (err) {
-          toolResult = { error: err.message };
-          toolErrorMessage = String(err.message || 'Tool execution failed');
-          failedStepCount++;
+          const currentRunMeta = engine.getRunMeta(runId);
+          toolInterruptedForPause = currentRunMeta?.status === 'pausing'
+            && currentRunMeta.abortController?.signal?.aborted === true;
+          toolErrorMessage = toolInterruptedForPause
+            ? 'The tool was interrupted for pause after dispatch; its external outcome is unknown.'
+            : String(err.message || 'Tool execution failed');
+          toolResult = toolInterruptedForPause
+            ? { status: 'outcome_unknown', error: toolErrorMessage }
+            : { error: err.message };
+          if (!toolInterruptedForPause) failedStepCount++;
           engine.detachProcessFromRun(runId, toolResult?.pid);
           db.prepare('UPDATE agent_steps SET status = ?, error = ?, completed_at = datetime(\'now\') WHERE id = ?')
-            .run('failed', err.message, stepId);
-          engine.emit(userId, 'run:tool_end', { runId, stepId, toolName, error: err.message, status: 'failed' });
-          engine.recordRunEvent(userId, runId, 'tool_failed', {
+            .run(toolInterruptedForPause ? 'paused' : 'failed', toolErrorMessage, stepId);
+          engine.emit(userId, 'run:tool_end', {
+            runId,
+            stepId,
+            toolName,
+            error: toolErrorMessage,
+            status: toolInterruptedForPause ? 'paused' : 'failed',
+          });
+          engine.recordRunEvent(userId, runId, toolInterruptedForPause ? 'tool_paused' : 'tool_failed', {
             toolName,
-            status: 'failed',
-            error: err.message,
+            status: toolInterruptedForPause ? 'paused' : 'failed',
+            error: toolErrorMessage,
             durationMs: Date.now() - stepStartedAt,
           }, { agentId, stepId });
           console.warn(
@@ -1991,11 +2175,26 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           );
         }
 
-        const execution = classifyToolExecution(toolName, toolArgs, toolResult, toolErrorMessage);
+        const lifecycleAfterTool = await engine.checkpointLifecycle(runId, 'tool_boundary', {
+          iteration,
+          stepIndex,
+        });
+        if (lifecycleAfterTool?.action === 'stop' || lifecycleAfterTool?.action === 'interrupt') break;
+
+        const execution = classifyToolExecution(
+          toolName,
+          toolArgs,
+          toolResult,
+          toolErrorMessage,
+          tools.find((tool) => tool?.name === toolName) || null,
+        );
         execution.input = toolArgs;
         const repetitionObservation = repetitionGuard?.observe(toolName, toolArgs, toolResult);
-        if ((execution.stateChanged && isProgressToolCall(toolName, toolArgs))
-          || gatheredNewEvidence(execution, repetitionObservation)) {
+        const toolMadeConcreteProgress = (
+          (execution.stateChanged && isProgressToolCall(toolName, toolArgs))
+          || gatheredNewEvidence(execution, repetitionObservation)
+        );
+        if (toolMadeConcreteProgress) {
           iterationConcreteProgress = true;
         }
         execution.artifacts = await extractArtifactsFromResult(toolName, toolResult);
@@ -2054,7 +2253,13 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           tools = engine.getActiveTools(runId);
         }
 
-        if (toolErrorMessage) {
+        if (toolInterruptedForPause) {
+          consecutiveToolFailures = 0;
+          messages.push({
+            role: 'system',
+            content: `The outcome of "${toolName}" is unknown because pause interrupted it after dispatch. Do not repeat the call. First inspect or query the affected state with a safe read-only tool, then continue based on verified evidence.`,
+          });
+        } else if (toolErrorMessage) {
           consecutiveToolFailures += 1;
           const currentRunMeta = engine.getRunMeta(runId);
           trackErrorPattern(toolErrorMessage, currentRunMeta);
@@ -2137,7 +2342,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
           currentTool: null,
           currentStepStartedAt: null,
         }, {
-          verified: true,
+          verified: toolMadeConcreteProgress,
           stepId,
         });
 
@@ -2182,22 +2387,23 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       if (!engine.activeRuns.has(runId)) break;
     }
 
+    const finalizingRunMeta = engine.getRunMeta(runId);
+    if (finalizingRunMeta) finalizingRunMeta.pauseAvailable = false;
+
     if (engine.isRunStopped(runId)) {
       const stoppedRunMeta = engine.getRunMeta(runId);
-      const terminalStatus = stoppedRunMeta?.status === 'interrupted' ? 'interrupted' : 'stopped';
+      const persistedTerminal = db.prepare(
+        'SELECT status, error FROM agent_runs WHERE id = ?',
+      ).get(runId);
+      const terminalStatus = persistedTerminal?.status === 'interrupted'
+        || 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)}] ${terminalStatus} trigger=${triggerSource} steps=${stepIndex} tokens=${totalTokens}`
       );
-      engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
+      await engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
       engine.stopMessagingProgressSupervisor(runId);
       engine.activeRuns.delete(runId);
       engine.emit(userId, terminalStatus === 'interrupted' ? 'run:interrupted' : 'run:stopped', {
@@ -2248,16 +2454,20 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     if (budgetExhaustedWithoutCompletion) {
       console.warn(`[Run ${shortenRunId(runId)}] max_iteration_wrapup model=${model} iteration=${iteration}/${maxIterations}`);
       try {
-        const wrapResponse = await withModelCallTimeout(
-          provider.chat(
+        const wrapResponse = await runAbortableModelCall(
+          (signal) => provider.chat(
             sanitizeConversationMessages([
               ...messages,
               { role: 'system', content: buildMaxIterationWrapupPrompt(options?.source || null) },
             ]),
             [],
-            { model, reasoningEffort: engine.getReasoningEffort(providerName, options) },
+            {
+              model,
+              reasoningEffort: engine.getReasoningEffort(providerName, options),
+              signal,
+            },
           ),
-          options,
+          { ...options, signal: engine.getRunMeta(runId)?.abortController?.signal },
           'Max-iteration wrap-up',
         );
         totalTokens += wrapResponse.usage?.totalTokens || 0;
@@ -2290,8 +2500,8 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       console.warn(`[Run ${shortenRunId(runId)}] blank_reply_recovery model=${model}`);
       let recoveredTokens = 0;
       try {
-        const recoveryResponse = await withModelCallTimeout(
-          provider.chat(
+        const recoveryResponse = await runAbortableModelCall(
+          (signal) => provider.chat(
             sanitizeConversationMessages([
               ...messages,
               {
@@ -2302,10 +2512,11 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
             [],
             {
               model,
-              reasoningEffort: engine.getReasoningEffort(providerName, options)
+              reasoningEffort: engine.getReasoningEffort(providerName, options),
+              signal,
             }
           ),
-          options,
+          { ...options, signal: engine.getRunMeta(runId)?.abortController?.signal },
           'Blank messaging reply recovery',
         );
         recoveredTokens = recoveryResponse.usage?.totalTokens || 0;
@@ -2318,7 +2529,9 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       // 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));
+      const recoveredVisible = Boolean(
+        normalizeOutgoingMessage(lastContent, options?.source || null),
+      );
       if (!recoveredVisible) {
         lastContent = buildDeterministicMessagingFallback({ failedStepCount, stepIndex, toolExecutions });
       }
@@ -2336,6 +2549,22 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       }
     }
 
+    const lifecycleBeforeFinalize = await engine.checkpointLifecycle(runId, 'finalization_boundary', {
+      iteration,
+      stepIndex,
+    });
+    if (
+      engine.isRunStopped(runId)
+      || lifecycleBeforeFinalize?.action === 'stop'
+      || lifecycleBeforeFinalize?.action === 'interrupt'
+    ) {
+      const terminal = db.prepare('SELECT status FROM agent_runs WHERE id = ?').get(runId)?.status || 'stopped';
+      await engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
+      engine.stopMessagingProgressSupervisor(runId);
+      engine.activeRuns.delete(runId);
+      return { runId, content: '', totalTokens, iterations: iteration, status: terminal };
+    }
+
     if (
       !normalizeOutgoingMessage(lastContent, options?.source || null)
       && !messagingSent
@@ -2448,6 +2677,9 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       });
     }
 
+    // Final reply terminality is decided by the AI completion judge / task_complete path.
+    // Do not phrase-match natural-language drafts here.
+
     if (deliverableWorkflow && deliverablePlan) {
       engine.recordRunEvent(userId, runId, 'deliverable_validation_started', {
         type: deliverableWorkflow.selection.type,
@@ -2492,8 +2724,23 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       db.prepare('UPDATE conversations SET total_tokens = total_tokens + ?, updated_at = datetime(\'now\') WHERE id = ?')
         .run(totalTokens, conversationId);
       if (options.skipConversationMaintenance !== true) {
-        refreshConversationSummary(conversationId, provider, model, historyWindow).catch((err) => {
-          console.error('[AI] Conversation summary refresh failed:', err.message);
+        engine.trackBackgroundTask(
+          (signal) => refreshConversationSummary(
+            conversationId,
+            provider,
+            model,
+            historyWindow,
+            false,
+            { signal },
+          ),
+          {
+            key: `conversation-summary:${conversationId}`,
+            signal: runMeta?.abortController?.signal || null,
+          },
+        ).catch((err) => {
+          if (!isAbortError(err, runMeta?.abortController?.signal) && !engine.shuttingDown) {
+            console.error('[AI] Conversation summary refresh failed:', err.message);
+          }
         });
       }
     }
@@ -2515,6 +2762,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     // Fallback: if this was a messaging-triggered run and no final delivery
     // was already sent in this run, auto-send the final assistant text.
     // Interim progress updates do not suppress this final delivery.
+    await engine.stopMessagingProgressSupervisor(runId);
     if (triggerSource === 'messaging' && options.source && options.chatId) {
       if (engine.shouldSendMessagingFinalFallback(runMeta, lastContent || '', options.source) && !lastFinalDeliveryMessage) {
         await engine.deliverMessagingFinalFallback({
@@ -2528,8 +2776,17 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       }
     }
 
-    db.prepare('UPDATE agent_runs SET status = ?, total_tokens = ?, final_response = ?, updated_at = datetime(\'now\'), completed_at = datetime(\'now\') WHERE id = ?')
-      .run('completed', totalTokens, finalResponseText || null, runId);
+    const completionWon = engine.completeRun(runId, {
+      totalTokens,
+      finalResponse: finalResponseText || null,
+    });
+    if (!completionWon) {
+      const terminal = db.prepare('SELECT status FROM agent_runs WHERE id = ?').get(runId)?.status || 'stopped';
+      await engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
+      engine.stopMessagingProgressSupervisor(runId);
+      engine.activeRuns.delete(runId);
+      return { runId, content: '', totalTokens, iterations: iteration, status: terminal };
+    }
 
     if (conversationId && options.skipConversationMaintenance !== true) {
       await engine.refreshConversationState({
@@ -2542,7 +2799,12 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
         analysis,
         verification,
         historyWindow,
-        options: { ...options, userId, agentId },
+        options: {
+          ...options,
+          userId,
+          agentId,
+          signal: engine.getRunMeta(runId)?.abortController?.signal || null,
+        },
       }).catch((err) => {
         console.error('[AI] Conversation working state refresh failed:', err.message);
       });
@@ -2551,7 +2813,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     console.info(
       `[Run ${shortenRunId(runId)}] completed trigger=${triggerSource} steps=${stepIndex} tokens=${totalTokens} durationMs=${runMeta?.startedAt ? Date.now() - runMeta.startedAt : 0} finalResponse=${finalResponseText ? 'yes' : 'no'} sentMessages=${runMeta?.sentMessages?.length || 0}`
     );
-    engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
+    await engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
     engine.stopMessagingProgressSupervisor(runId);
     engine.activeRuns.delete(runId);
     engine.emit(userId, 'run:complete', {
@@ -2584,12 +2846,16 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
     // Fire-and-forget: plugins can use this for self-improvement, memory
     // consolidation, analytics, or other post-run housekeeping.
     if (globalHooks.has('on_loop_end')) {
-      globalHooks.run('on_loop_end', {
-        userId, runId, agentId, status: 'completed',
-        iterations: iteration, totalTokens,
-        taskAnalysis: analysis,
-        finalContent: finalResponseText,
-      }).catch(() => {});
+      engine.trackBackgroundTask(
+        (signal) => globalHooks.run('on_loop_end', {
+          userId, runId, agentId, status: 'completed',
+          iterations: iteration, totalTokens,
+          taskAnalysis: analysis,
+          finalContent: finalResponseText,
+          signal,
+        }),
+        { signal: runMeta?.abortController?.signal || null },
+      ).catch(() => {});
     }
     if (engine.learningManager) {
       try {
@@ -2615,25 +2881,37 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
 
     return { runId, content: lastContent, totalTokens, iterations: iteration, status: 'completed' };
   } catch (err) {
+    if (!runRecordCreated) throw err;
     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 persistedTerminal = db.prepare(
+        'SELECT status, error FROM agent_runs WHERE id = ?',
+      ).get(runId);
+      const terminalStatus = persistedTerminal?.status === 'interrupted'
+        || stoppedRunMeta?.status === 'interrupted'
+        ? 'interrupted'
+        : 'stopped';
       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 });
+      await 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,
+        reason: stoppedRunMeta?.stopReason || persistedTerminal?.error || null,
+      });
+      engine.recordRunEvent(userId, terminalStatus === 'interrupted' ? 'run_interrupted' : 'run_stopped', {
         triggerSource,
         totalTokens,
         iterations: iteration,
       }, { agentId });
-      return { runId, content: '', totalTokens, iterations: iteration, status: 'stopped' };
+      return { runId, content: '', totalTokens, iterations: iteration, status: terminalStatus };
     }
 
     const runMeta = engine.activeRuns.get(runId);
+    await engine.stopMessagingProgressSupervisor(runId);
 
     const deliverableFailureResponse = err?.deliverableResult?.summary
       || err?.deliverableValidation?.summary
@@ -2657,16 +2935,19 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
               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, [], {
+          const modelReply = await runAbortableModelCall(
+            (signal) => provider.chat(failedMessage, [], {
               model,
-              reasoningEffort: engine.getReasoningEffort(providerName, options)
+              reasoningEffort: engine.getReasoningEffort(providerName, options),
+              signal,
             }),
-            options,
+            { ...options, signal: runMeta?.abortController?.signal },
             'Messaging failure reply',
           );
           const drafted = sanitizeModelOutput(modelReply.content || '', { model });
-          if (normalizeOutgoingMessage(drafted, options?.source || null)) {
+          if (
+            normalizeOutgoingMessage(drafted, options?.source || null)
+          ) {
             messagingFailureContent = drafted.trim();
           }
         } catch {
@@ -2688,7 +2969,11 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
             options.source,
             options.chatId,
             messagingFailureContent,
-            { runId, agentId },
+            {
+              runId,
+              agentId,
+              signal: runMeta?.abortController?.signal || null,
+            },
           );
           requireSuccessfulMessagingDelivery(deliveryResult, 'Messaging failure delivery');
           sendSucceeded = true;
@@ -2705,20 +2990,25 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       }
     }
 
-    db.prepare('UPDATE agent_runs SET status = ?, error = ?, final_response = ?, updated_at = datetime(\'now\') WHERE id = ?')
-      .run(
-        'failed',
-        err.message,
-        sendSucceeded
-          ? (messagingFailureContent || null)
-          : (deliverableFailureResponse || null),
-        runId,
-      );
+    const failureWon = engine.failRun(runId, {
+      error: err.message,
+      finalResponse: sendSucceeded
+        ? (messagingFailureContent || null)
+        : (deliverableFailureResponse || null),
+      totalTokens,
+    });
+    if (!failureWon) {
+      await engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
+      engine.stopMessagingProgressSupervisor(runId);
+      engine.activeRuns.delete(runId);
+      const terminal = db.prepare('SELECT status FROM agent_runs WHERE id = ?').get(runId)?.status || 'stopped';
+      return { runId, content: '', totalTokens, iterations: iteration, status: terminal };
+    }
     console.error(
       `[Run ${shortenRunId(runId)}] failed trigger=${triggerSource} steps=${stepIndex} tokens=${totalTokens} error=${summarizeForLog(err.message, 180)}`
     );
 
-    engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
+    await engine.cleanupSubagentsForRun(runId, { cancelRunning: true });
     engine.stopMessagingProgressSupervisor(runId);
     engine.activeRuns.delete(runId);
     engine.emit(userId, 'run:error', { runId, error: err.message });
@@ -2728,17 +3018,6 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
       iterations: iteration,
       deliverableType: deliverableWorkflow?.selection?.type || null,
     }, { agentId });
-    timelineService?.recordRunLifecycle?.({
-      userId,
-      agentId,
-      runId,
-      title: runTitle,
-      eventKind: 'run_failed',
-      status: 'failed',
-      triggerSource,
-      error: err.message,
-    });
-
     if (messagingFailureContent) {
       return {
         runId,
@@ -2751,6 +3030,7 @@ async function runConversation(engine, userId, userMessage, options = {}, _model
 
     throw err;
   } finally {
+    detachExternalAbort?.();
     releaseReservation();
   }
 }