neoagent 3.2.1-beta.10 → 3.2.1-beta.12

package/server/routes/behavior.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const express = require('express');
+const { requireAuth } = require('../middleware/auth');
+const {
+  MODULE_IDS,
+  cloneDefaults,
+  getBehaviorConfig,
+  setBehaviorConfig,
+  resolveBehaviorConfig,
+} = require('../services/behavior');
+const {
+  getAgentIdFromRequest,
+  resolveAgentId,
+} = require('../services/agents/manager');
+const { invalidateSystemPromptCache } = require('../services/ai/systemPrompt');
+
+const router = express.Router();
+router.use(requireAuth);
+
+function requestAgentId(req) {
+  return resolveAgentId(req.session.userId, getAgentIdFromRequest(req));
+}
+
+router.get('/', (req, res) => {
+  const userId = req.session.userId;
+  const agentId = requestAgentId(req);
+  res.json({
+    agentId,
+    modules: MODULE_IDS,
+    defaults: cloneDefaults(),
+    config: getBehaviorConfig(userId, agentId),
+  });
+});
+
+router.put('/', (req, res) => {
+  if (!req.body?.config || typeof req.body.config !== 'object' || Array.isArray(req.body.config)) {
+    return res.status(400).json({ error: 'config must be an object' });
+  }
+  const userId = req.session.userId;
+  const agentId = requestAgentId(req);
+  const config = setBehaviorConfig(userId, agentId, req.body.config);
+  invalidateSystemPromptCache(userId, agentId);
+  return res.json({ agentId, config });
+});
+
+router.get('/effective', (req, res) => {
+  const userId = req.session.userId;
+  const agentId = requestAgentId(req);
+  const platform = String(req.query.platform || '').trim();
+  const chatId = String(req.query.chatId || '').trim();
+  if (!platform || !chatId) {
+    return res.status(400).json({ error: 'platform and chatId are required' });
+  }
+  return res.json({
+    agentId,
+    config: resolveBehaviorConfig(userId, agentId, {
+      platform,
+      chatId,
+      isGroup: req.query.isGroup !== 'false',
+    }),
+  });
+});
+
+router.get('/diagnostics', (req, res) => {
+  const userId = req.session.userId;
+  const agentId = requestAgentId(req);
+  const platform = String(req.query.platform || '').trim();
+  const chatId = String(req.query.chatId || '').trim();
+  if (!platform || !chatId) {
+    return res.status(400).json({ error: 'platform and chatId are required' });
+  }
+  const pipeline = req.app?.locals?.behaviorPipeline;
+  if (!pipeline?.getDiagnostics) {
+    return res.status(503).json({ error: 'Behavior runtime is not initialized' });
+  }
+  return res.json(pipeline.getDiagnostics(userId, agentId, platform, chatId));
+});
+
+module.exports = router;

package/server/routes/settings.js

@@ -346,6 +346,10 @@ router.put('/', async (req, res) => {
   });
 
   tx(Object.entries(normalizedBody));
+  if (Object.prototype.hasOwnProperty.call(normalizedBody, 'assistant_behavior_notes')) {
+    const { invalidateSystemPromptCache } = require('../services/ai/systemPrompt');
+    invalidateSystemPromptCache(userId, agentId);
+  }
 
   if (Object.keys(normalizedBody).some((key) => VOICE_SETTING_KEYS.has(key))) {
     const manager = req.app?.locals?.messagingManager;

package/server/services/ai/history.js

@@ -126,7 +126,7 @@ async function summarizeMessages(
   const prompt = [
     {
       role: 'system',
-      content: 'Compress conversation context. Preserve user goals, constraints, preferences, decisions, promised follow-ups, recurring schedules, important facts, tool outcomes, and unresolved issues. Keep concrete details (names, dates, times, statuses) and avoid vague wording. Keep the same personality context, including the favorite-contact texting register when relevant. Output plain text only.'
+      content: 'Compress conversation context. Preserve user goals, constraints, preferences, decisions, promised follow-ups, recurring schedules, important facts, tool outcomes, unresolved issues, and any user-stated communication preferences. Keep concrete details (names, dates, times, statuses) and avoid vague wording. Output plain text only.'
     },
     {
       role: 'user',

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

@@ -20,6 +20,10 @@ const { summarizeCapabilityHealth } = require('../capabilityHealth');
 const { shouldAcceptTaskComplete } = require('../completion');
 const { shortenRunId, summarizeForLog } = require('../logFormat');
 const { getProviderForUser } = require('../provider_selector');
+const {
+  recordModelFailure,
+  recordModelSuccess,
+} = require('../model_failure_cache');
 const { runConversation } = require('./conversation_loop');
 const {
   TERMINAL_STATUSES,
@@ -638,6 +642,82 @@ class AgentEngine {
     });
   }
 
+  async inferStructured({
+    userId,
+    agentId = null,
+    modelId = null,
+    purpose = 'fast',
+    system,
+    prompt,
+    maxTokens = 400,
+    fallback = {},
+    signal = null,
+  }) {
+    const { getFailureFallbackModelId } = require('./conversation_loop');
+    const configuredFallbackId = getAiSettings(userId, agentId).fallback_model_id;
+    const failedModelIds = new Set();
+    let requestedModelId = modelId;
+    let selected = null;
+    let result = null;
+
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      selected = await getProviderForUser(
+        userId,
+        prompt,
+        false,
+        requestedModelId,
+        {
+          agentId,
+          signal,
+          selectionHint: {
+            purpose: purpose === 'general' ? 'general' : 'fast',
+            costMode: purpose === 'fast' ? 'economy' : 'balanced_auto',
+          },
+        },
+      );
+      try {
+        result = await this.requestStructuredJson({
+          provider: selected.provider,
+          providerName: selected.providerName,
+          model: selected.model,
+          messages: system ? [{ role: 'system', content: String(system) }] : [],
+          prompt: String(prompt || ''),
+          maxTokens,
+          normalize: (value) => value,
+          fallback,
+          telemetry: { userId, agentId, signal },
+          phase: 'behavior_inference',
+        });
+        recordModelSuccess(userId, agentId, selected.modelSelectionId);
+        break;
+      } catch (error) {
+        if (isAbortError(error, signal) || signal?.aborted) throw error;
+        recordModelFailure(userId, agentId, selected.modelSelectionId, error);
+        failedModelIds.add(selected.modelSelectionId);
+        if (attempt >= 2) throw error;
+        requestedModelId = await getFailureFallbackModelId(
+          userId,
+          agentId,
+          selected.modelSelectionId,
+          configuredFallbackId,
+          error,
+          signal,
+          failedModelIds,
+        );
+        if (!requestedModelId) throw error;
+      }
+    }
+
+    return {
+      parsed: result.value,
+      raw: result.raw,
+      usage: result.usage,
+      model: selected.model,
+      modelSelectionId: selected.modelSelectionId,
+      providerName: selected.providerName,
+    };
+  }
+
   async requestModelResponse({
     provider,
     providerName,
@@ -973,6 +1053,15 @@ class AgentEngine {
         content: [
           'Return JSON only. Distill the current thread working state. Keep it concise and concrete.',
           'Track summary, open_commitments, unresolved_questions, referenced_entities, and last_verified_facts. Do not invent facts.',
+          options.memoryScope?.scopeType === 'channel'
+            ? [
+                'This is a shared room. Extract only durable room or participant facts that are safe and useful in this room.',
+                'Do not infer or store facts about the authenticated owner from another participant’s message.',
+                options.context?.socialIntelligence?.message?.sender
+                  ? `For facts about the current speaker, use the canonical subject "${options.source}:${options.context.socialIntelligence.message.sender}".`
+                  : '',
+              ].filter(Boolean).join(' ')
+            : '',
           buildMemoryConsolidationInstructions(new Date().toISOString()),
           'Schema:',
           JSON.stringify({
@@ -1049,6 +1138,14 @@ class AgentEngine {
           agentId: options.agentId || null,
           conversationId,
           runId,
+          scope: options.memoryScope || undefined,
+          metadata: options.memoryScope
+            ? {
+                trustLevel: 'shared_room_conversation',
+                platform: options.source || null,
+                chatId: options.chatId || null,
+              }
+            : undefined,
           signal: options.signal,
         },
       );
@@ -1245,22 +1342,6 @@ class AgentEngine {
     return options.reasoningEffort || process.env.REASONING_EFFORT || 'low';
   }
 
-  shouldFastCompleteVoiceReply({
-    options = {},
-    toolExecutions = [],
-    failedStepCount = 0,
-    messagingSent = false,
-    lastReply = '',
-  }) {
-    // Voice fast-path is structural only: short reply, no tools/failures.
-    // Content terminality is left to the model completion judge.
-    return options.latencyProfile === 'voice'
-      && toolExecutions.length === 0
-      && failedStepCount === 0
-      && !messagingSent
-      && Boolean(String(lastReply || '').trim());
-  }
-
   getMessagingRetryLimit(maxIterations) {
     // Cap at 3: more than 3 autonomous messaging retries indicates a structural
     // problem (model unavailable, bad config) that more retries won't solve.

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

@@ -6,6 +6,7 @@ const {
   assessResearchAdequacy,
   formatResearchAdequacyGuidance,
   summarizeAvailableTools,
+  summarizeResearchEvidenceCatalog,
   summarizeToolExecutions,
 } = require('../toolEvidence');
 
@@ -208,7 +209,7 @@ function buildCompletionDecisionPrompt({
   const lines = [
     'Return JSON only.',
     'Decide whether this run should continue autonomously or stop now.',
-    'Schema: {"status":"continue|complete|blocked","reason":"short concrete reason"}',
+    'Schema: {"status":"continue|complete|blocked","reason":"short concrete reason","blocker_review":{"kind":"user_input|permission|external_dependency|unavailable_capability|none","resolvable_in_run":true,"required_value":"specific missing dependency"},"research_review":{"required":true,"adequate":false,"overall_support":"primary|secondary|context|none","evidence_indexes":[1],"target_coverage":[{"target":"exact requested target","support":"primary|secondary|context|none","evidence_indexes":[1]}],"missing_targets":["exact missing target"]}}',
     'Rules:',
     '- Use "continue" whenever any safe next step remains in this same run.',
     '- Use "complete" when the requested outcome is achieved, already done, or a no-op because there is nothing matching the request to change, and the latest draft is the finished user-facing answer.',
@@ -219,8 +220,12 @@ function buildCompletionDecisionPrompt({
     '- A tool-specific API error, timeout, rate limit, or missing result inside this run is usually "continue", not "blocked", if any other available tool could still make progress.',
     '- Repeated read-only inspection that has already established the relevant object is absent or unchanged is not progress. Accept a concise complete/blocker reply instead of requiring more searching.',
     `- If completion_confidence_required is ${goalContext.effectiveCompletionConfidence} and the latest draft depends on unverified assumptions, use "continue" so the run can gather evidence, inspect state, or narrow the reply.`,
-    '- When research intensity is light or deep, use "continue" until the required primary/source coverage and target coverage are met, or the draft is an explicit blocker naming exactly what could not be verified.',
+    '- When research intensity is light or deep, fill research_review from the numbered evidence entries. Do not mark complete unless every requested target has concrete support.',
     '- Search snippets, memory, and model priors are leads, not completion evidence. Prefer opened/fetched primary sources before "complete".',
+    '- Judge source quality semantically from the actual evidence summary. Tool names, call counts, local notes, and target words in tool arguments do not by themselves make evidence primary or prove a claim.',
+    '- evidence_indexes are the numeric parts of E identifiers from the Research evidence catalog. Never cite an entry that does not support the target.',
+    '- A real external blocker or genuinely required user input may be "blocked" even when research is incomplete. Name the missing dependency precisely; do not pretend more autonomous research can resolve user-only information.',
+    '- For "blocked", blocker_review.kind must identify the external dependency, resolvable_in_run must be false, and required_value must state what is missing. Otherwise choose "continue".',
     '- If the latest draft invents entities, products, people, files, results, or actions that are not supported by tool evidence, use "continue" so the run can gather evidence or rewrite into a truthful partial/blocker answer.',
     '- A polished-sounding answer is not complete if key requested targets still lack direct evidence.',
     '- If the latest draft only announces unfinished work, promises a future update, or asks the user to wait without a concrete result or blocker, use "continue" so the run keeps acting.',
@@ -229,12 +234,12 @@ function buildCompletionDecisionPrompt({
 
   if (adequacy.intensity !== 'none') {
     lines.push(
-      `- Research intensity for this run is ${adequacy.intensity}. Current coverage: primary=${adequacy.primarySourceCount}/${adequacy.requiredPrimarySources}, secondary=${adequacy.secondarySourceCount}, targets_covered=${adequacy.coveredTargets.length}/${Math.max(adequacy.requiredTargetCoverage, adequacy.targets.length)}.`,
+      `- Research intensity for this run is ${adequacy.intensity}. Successful evidence candidates=${adequacy.evidenceCandidateCount}; unique calls=${adequacy.uniqueEvidenceCandidateCount}. Semantic target coverage has not been precomputed.`,
     );
   }
-  if (adequacy.adequate === false) {
+  if (adequacy.structurallyReady === false) {
     lines.push(
-      `- Research is still incomplete (${adequacy.reason}). Use "continue" unless the latest draft is an explicit blocker naming the exact missing evidence.`,
+      `- No source evidence is ready for review (${adequacy.reason}). Use "continue" unless the latest draft is a real external blocker.`,
     );
   }
 
@@ -255,31 +260,176 @@ function buildCompletionDecisionPrompt({
       : '',
     `Current iteration: ${iteration} of ${maxIterations}.`,
     `Available tools in this run: ${summarizeAvailableTools(tools) || 'none'}`,
-    `Recent tool evidence:\n${summarizeToolExecutions(toolExecutions, 8) || 'none'}`,
+    `Recent tool evidence:\n${summarizeToolExecutions(toolExecutions, 12) || 'none'}`,
     adequacy.intensity !== 'none'
-      ? `Research adequacy: intensity=${adequacy.intensity}; adequate=${adequacy.adequate}; reason=${adequacy.reason}`
+      ? `Research evidence catalog:\n${summarizeResearchEvidenceCatalog(toolExecutions) || 'none'}`
+      : '',
+    adequacy.intensity !== 'none'
+      ? `Research preflight: intensity=${adequacy.intensity}; structurally_ready=${adequacy.structurallyReady}; semantic_review_required=true; reason=${adequacy.reason}`
       : '',
     adequacy.targets.length
       ? `Research targets: ${adequacy.targets.join('; ')}`
       : '',
-    adequacy.uncoveredTargets.length
-      ? `Uncovered research targets: ${adequacy.uncoveredTargets.join('; ')}`
-      : '',
     formatResearchAdequacyGuidance(adequacy),
     `Latest draft reply:\n${draftReply || '(empty)'}`,
   );
   return lines.filter(Boolean).join('\n');
 }
 
+function normalizeEvidenceIndexes(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value
+    .map((entry) => Number(entry))
+    .filter((entry) => Number.isInteger(entry) && entry > 0))]
+    .slice(0, 20);
+}
+
+function normalizeResearchReview(raw = null) {
+  const review = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  const targetCoverage = Array.isArray(review.target_coverage || review.targetCoverage)
+    ? (review.target_coverage || review.targetCoverage)
+      .filter((entry) => entry && typeof entry === 'object' && !Array.isArray(entry))
+      .map((entry) => ({
+        target: String(entry.target || '').trim(),
+        support: ['primary', 'secondary', 'context', 'none'].includes(
+          String(entry.support || '').trim().toLowerCase(),
+        )
+          ? String(entry.support).trim().toLowerCase()
+          : 'none',
+        evidence_indexes: normalizeEvidenceIndexes(
+          entry.evidence_indexes || entry.evidenceIndexes,
+        ),
+      }))
+      .filter((entry) => entry.target)
+      .slice(0, 12)
+    : [];
+  return {
+    required: review.required === true,
+    adequate: review.adequate === true,
+    overall_support: ['primary', 'secondary', 'context', 'none'].includes(
+      String(review.overall_support || review.overallSupport || '').trim().toLowerCase(),
+    )
+      ? String(review.overall_support || review.overallSupport).trim().toLowerCase()
+      : 'none',
+    evidence_indexes: normalizeEvidenceIndexes(
+      review.evidence_indexes || review.evidenceIndexes,
+    ),
+    target_coverage: targetCoverage,
+    missing_targets: normalizeGoalCriteria(
+      review.missing_targets || review.missingTargets || [],
+    ),
+  };
+}
+
 function normalizeCompletionDecision(raw, fallbackStatus = 'continue') {
   const allowed = new Set(['continue', 'complete', 'blocked']);
   const requestedStatus = String(raw.status || '').trim().toLowerCase();
+  const rawBlockerReview = raw.blocker_review || raw.blockerReview;
+  const blockerReview = rawBlockerReview
+    && typeof rawBlockerReview === 'object'
+    && !Array.isArray(rawBlockerReview)
+    ? rawBlockerReview
+    : {};
+  const blockerKind = String(blockerReview.kind || '').trim().toLowerCase();
   return {
     status: allowed.has(requestedStatus) ? requestedStatus : fallbackStatus,
     reason: String(raw.reason || '').trim().slice(0, 400),
+    blocker_review: {
+      kind: [
+        'user_input',
+        'permission',
+        'external_dependency',
+        'unavailable_capability',
+        'none',
+      ].includes(blockerKind)
+        ? blockerKind
+        : 'none',
+      resolvable_in_run: blockerReview.resolvable_in_run !== false
+        && blockerReview.resolvableInRun !== false,
+      required_value: String(
+        blockerReview.required_value || blockerReview.requiredValue || '',
+      ).trim().slice(0, 300),
+    },
+    research_review: normalizeResearchReview(
+      raw.research_review || raw.researchReview,
+    ),
   };
 }
 
+function validateResearchReview(review, researchAdequacy, toolExecutions = []) {
+  if (!researchAdequacy || researchAdequacy.intensity === 'none') {
+    return { valid: true, reason: '' };
+  }
+  if (researchAdequacy.structurallyReady === false) {
+    return {
+      valid: false,
+      reason: researchAdequacy.reason || 'No successful source evidence is available.',
+    };
+  }
+  if (!review?.required || review.adequate !== true) {
+    return {
+      valid: false,
+      reason: 'The completion judge did not confirm adequate research evidence.',
+    };
+  }
+
+  const isValidEvidenceIndex = (index) => {
+    const execution = (Array.isArray(toolExecutions) ? toolExecutions : [])[index - 1];
+    return Boolean(
+      execution
+      && execution.ok === true
+      && execution.evidenceRelevant !== false
+      && execution.evidenceSource !== 'messaging',
+    );
+  };
+  const hasValidEvidence = (indexes) => (
+    Array.isArray(indexes) && indexes.some(isValidEvidenceIndex)
+  );
+  const requiredTargets = Array.isArray(researchAdequacy.targets)
+    ? researchAdequacy.targets
+    : [];
+
+  if (requiredTargets.length === 0) {
+    const reviewIndexes = [
+      ...(review.evidence_indexes || []),
+      ...(review.target_coverage || []).flatMap((entry) => entry.evidence_indexes || []),
+    ];
+    if (!hasValidEvidence(reviewIndexes)) {
+      return { valid: false, reason: 'The research review cites no successful evidence entry.' };
+    }
+    if (researchAdequacy.intensity === 'deep' && review.overall_support !== 'primary') {
+      return { valid: false, reason: 'Deep research lacks primary source support.' };
+    }
+    if (review.overall_support === 'none') {
+      return { valid: false, reason: 'The research review did not classify its source support.' };
+    }
+    return { valid: true, reason: '' };
+  }
+
+  const coverageByTarget = new Map(
+    (review.target_coverage || []).map((entry) => [
+      String(entry.target || '').trim().toLowerCase(),
+      entry,
+    ]),
+  );
+  for (const target of requiredTargets) {
+    const coverage = coverageByTarget.get(String(target).trim().toLowerCase());
+    if (!coverage || coverage.support === 'none' || !hasValidEvidence(coverage.evidence_indexes)) {
+      return {
+        valid: false,
+        reason: `The research review does not cite supporting evidence for "${target}".`,
+      };
+    }
+    if (researchAdequacy.intensity === 'deep' && coverage.support !== 'primary') {
+      return {
+        valid: false,
+        reason: `Deep research still lacks primary evidence for "${target}".`,
+      };
+    }
+  }
+  return { valid: true, reason: '' };
+}
+
 function enforceTerminalReplyDecision(decision, lastReply, options = {}) {
   // Natural-language terminality is judged by the model completion decision.
   // Runtime only enforces structural evidence contracts (research adequacy).
@@ -289,25 +439,33 @@ function enforceTerminalReplyDecision(decision, lastReply, options = {}) {
       goalContext: options.goalContext || null,
       toolExecutions: options.toolExecutions || [],
     });
-  if (
-    researchAdequacy
-    && researchAdequacy.adequate === false
-    && (decision?.status === 'complete' || decision?.status === 'blocked')
-  ) {
-    // Allow true blocked outcomes only when the model already chose blocked AND
-    // research cannot progress further (no remaining targets/primary gap that
-    // tools could still cover). Otherwise force continue for evidence gathering.
+  if (decision?.status === 'blocked') {
+    const blockerReview = decision.blocker_review;
     if (
-      decision?.status === 'blocked'
-      && researchAdequacy.uncoveredTargets.length === 0
-      && researchAdequacy.primarySourceCount >= researchAdequacy.requiredPrimarySources
+      blockerReview
+      && blockerReview.kind !== 'none'
+      && blockerReview.resolvable_in_run === false
+      && blockerReview.required_value
     ) {
       return decision;
     }
     return {
+      ...decision,
       status: 'continue',
-      reason: researchAdequacy.reason
-        || 'Research evidence is still incomplete for the requested targets; continue gathering sources before finishing.',
+      reason: 'The completion judge did not substantiate a blocker that requires external input or state.',
+    };
+  }
+  if (decision?.status === 'complete') {
+    const reviewValidation = validateResearchReview(
+      decision.research_review,
+      researchAdequacy,
+      options.toolExecutions || [],
+    );
+    if (reviewValidation.valid) return decision;
+    return {
+      status: 'continue',
+      reason: reviewValidation.reason,
+      research_review: decision.research_review,
     };
   }
   return decision;
@@ -332,7 +490,7 @@ function buildChurnAssessmentPrompt({
   const lines = [
     'Return JSON only.',
     'Self-assess your current loop state — are you making genuine progress or spinning?',
-    'Schema: {"assessment":"progressing|churn|blocked","reason":"one short concrete sentence"}',
+    'Schema: {"assessment":"progressing|churn|blocked","reason":"one short concrete sentence","blocker_kind":"user_input|permission|external_dependency|unavailable_capability|none","resolvable_in_run":true}',
     '',
     `Context: ${readOnlyCount} consecutive iteration(s) with only read/search/inspect operations — no concrete state changes yet.`,
     alreadyRead ? `Already inspected: ${alreadyRead}.` : '',
@@ -343,44 +501,39 @@ function buildChurnAssessmentPrompt({
     `Iteration: ${iteration}`,
     `Recent tool evidence:\n${summarizeToolExecutions(toolExecutions, 6) || 'none'}`,
     adequacy.intensity !== 'none'
-      ? `Research adequacy: intensity=${adequacy.intensity}; adequate=${adequacy.adequate}; covered=${adequacy.coveredTargets.length}/${Math.max(adequacy.requiredTargetCoverage, adequacy.targets.length)}; primary=${adequacy.primarySourceCount}/${adequacy.requiredPrimarySources}.`
+      ? `Research preflight: intensity=${adequacy.intensity}; evidence_candidates=${adequacy.evidenceCandidateCount}; semantic target coverage must be judged from the evidence summaries.`
       : '',
-    adequacy.uncoveredTargets.length
-      ? `Still uncovered research targets: ${adequacy.uncoveredTargets.join('; ')}.`
+    adequacy.targets.length
+      ? `Requested research targets: ${adequacy.targets.join('; ')}.`
       : '',
     '',
     'Assessment rules:',
     '- "progressing": You are systematically gathering necessary context and the next concrete action is already determined — you know exactly what to do next.',
     '- "churn": You are re-reading/re-searching information already in context, or exploring without a clear next concrete step. Accept the nudge and act.',
     '- "blocked": No concrete action is available in this run. You have all the evidence needed to deliver a truthful final answer or a specific external blocker.',
+    '- Use "blocked" only with a non-none blocker_kind and resolvable_in_run=false. Partial evidence, a failed attempt, or uncertainty is not by itself an external blocker.',
     '- For multi-target research, keep "progressing" while uncovered targets remain and a fresh primary source can still be opened. Do not mark "blocked" just because you have partial notes.',
     '- Re-querying the same snippet source for an already covered target is "churn". Opening a different primary source for an uncovered target is "progressing".',
-    adequacy.adequate === false
-      ? '- Research adequacy is currently incomplete. Prefer "progressing" if a new primary source for an uncovered target is still available; use "churn" only for repeated identical reads; do not use "blocked" unless tools cannot reach remaining targets.'
+    adequacy.structurallyReady === false
+      ? '- No successful source evidence exists yet. Prefer "progressing" if a concrete source-gathering step remains, but use "blocked" for a genuine external dependency or required user input.'
       : '',
   ];
   return lines.filter(Boolean).join('\n');
 }
 
-function enforceChurnAssessment(assessment, options = {}) {
+function enforceChurnAssessment(assessment) {
   const normalized = normalizeChurnAssessment(assessment);
-  const researchAdequacy = options.researchAdequacy
-    || assessResearchAdequacy({
-      analysis: options.analysis || null,
-      goalContext: options.goalContext || null,
-      toolExecutions: options.toolExecutions || [],
-    });
   if (
-    researchAdequacy
-    && researchAdequacy.adequate === false
-    && researchAdequacy.intensity !== 'none'
-    && normalized.assessment === 'blocked'
-    && (researchAdequacy.uncoveredTargets?.length > 0 || researchAdequacy.primarySourceCount < researchAdequacy.requiredPrimarySources)
+    normalized.assessment === 'blocked'
+    && (
+      normalized.blocker_kind === 'none'
+      || normalized.resolvable_in_run !== false
+    )
   ) {
     return {
-      assessment: 'progressing',
-      reason: researchAdequacy.reason
-        || 'Research targets remain uncovered; keep gathering primary sources instead of force-finishing.',
+      ...normalized,
+      assessment: 'churn',
+      reason: 'The churn assessment did not identify a concrete external blocker.',
     };
   }
   return normalized;
@@ -389,9 +542,21 @@ function enforceChurnAssessment(assessment, options = {}) {
 function normalizeChurnAssessment(raw) {
   const allowed = new Set(['progressing', 'churn', 'blocked']);
   const assessment = String(raw?.assessment || '').trim().toLowerCase();
+  const blockerKind = String(raw?.blocker_kind || raw?.blockerKind || '').trim().toLowerCase();
   return {
     assessment: allowed.has(assessment) ? assessment : 'churn',
     reason: String(raw?.reason || '').trim().slice(0, 300),
+    blocker_kind: [
+      'user_input',
+      'permission',
+      'external_dependency',
+      'unavailable_capability',
+      'none',
+    ].includes(blockerKind)
+      ? blockerKind
+      : 'none',
+    resolvable_in_run: raw?.resolvable_in_run !== false
+      && raw?.resolvableInRun !== false,
   };
 }
 
@@ -406,6 +571,8 @@ module.exports = {
   enforceChurnAssessment,
   normalizeChurnAssessment,
   normalizeCompletionDecision,
+  normalizeResearchReview,
   normalizeGoalContract,
   resolveRunGoalContext,
+  validateResearchReview,
 };