@yemi33/minions 0.1.2423 → 0.1.2425

package/engine/lifecycle.js

@@ -10,12 +10,16 @@ const shared = require('./shared');
 const { safeRead, safeJson, safeJsonArr, safeJsonNoRestore, safeWrite, mutateJsonFileLocked, mutateWorkItems, execAsync, getPrLinks,
   log, ts, dateStamp, WI_STATUS, DONE_STATUSES, PLAN_TERMINAL_STATUSES, WORK_TYPE, PLAN_STATUS, PRD_ITEM_STATUS, PRD_MATERIALIZABLE, PR_STATUS, REVIEW_STATUS, RETRY_DELAY_MS, DISPATCH_RESULT,
   ENGINE_DEFAULTS, DEFAULT_AGENT_METRICS, FAILURE_CLASS } = shared;
-const { resolveRuntime } = require('./runtimes');
+const { resolveRuntime, hasUnfinishedToolCall } = require('./runtimes');
 const adoGitAuth = require('./ado-git-auth');
 const queries = require('./queries');
 const harness = require('./harness');
+const reviewLearning = require('./review-learning');
 const smallStateStore = require('./small-state-store');
 const prdStore = require('./prd-store');
+const features = require('./features');
+const memoryStore = require('./memory-store');
+const promotion = require('./promotion');
 const { isBranchActive } = require('./cooldown');
 const { resolveExecutionModel } = require('./execution-model');
 const { worktreeMatchesBranch, getWorktreeBranch, cleanupMergedPrLocalBranch } = require('./cleanup');
@@ -2563,6 +2567,7 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
       // Drop it when reviewer requests changes again — that starts a new fix cycle.
       ...(target.minionsReview?.fixedAt && postReviewStatus !== REVIEW_STATUS.CHANGES_REQUESTED ? { fixedAt: target.minionsReview.fixedAt } : {}),
     };
+    target.minionsReview.findingIdentity = shared.prReviewFindingIdentity(target);
     updatedTarget = { ...reviewPr, ...target };
     return prs;
   }, { defaultValue: [] });
@@ -2585,6 +2590,9 @@ async function updatePrAfterReview(agentId, pr, project, config, resultSummary,
       project: reviewProject,
       dispatchId: dispatchItem?.id || structuredCompletion?.dispatchId || null,
       sourceItem: dispatchItem?.meta?.item?.id || null,
+      postReviewStatus,
+      reviewVerdict: verdictRaw,
+      findingIdentity: shared.prReviewFindingIdentity(updatedTarget),
     });
   }
 }
@@ -3820,18 +3828,15 @@ function extractSkillsFromOutput(output, agentId, dispatchItem, config, runtimeN
         const projectSkillRoot = skillWriteTargets(effectiveRuntime, proj).project
           || path.resolve(proj.localPath, '.claude', 'skills');
         const projectSkillPath = path.join(projectSkillRoot, skillDirName, 'SKILL.md');
-        let skillId = null;
-        mutateWorkItems('central', data => {
-          data = data || [];
-          if (data.some(i => i.title === `Add skill: ${name}` && i.status !== WI_STATUS.FAILED)) return data;
-          skillId = `SK${String(data.filter(i => i.id?.startsWith('SK')).length + 1).padStart(3, '0')}`;
-          data.push({ id: skillId, type: WORK_TYPE.IMPLEMENT, title: `Add skill: ${name}`,
-            description: `Create project-level skill \`${skillDirName}/SKILL.md\` in ${project}.\n\nWrite this file to \`${projectSkillPath}\` via a PR.\n\n## Skill Content\n\n\`\`\`\n${enrichedBlock}\n\`\`\``,
-            priority: 'low', status: WI_STATUS.QUEUED, created: ts(), createdBy: `engine:skill-extraction:${agentName}` });
-          return data;
+        const queued = promotion.queueProjectSkillWorkItem({
+          config,
+          projectName: project,
+          skillName: name,
+          description: `Create project-level skill \`${skillDirName}/SKILL.md\` in ${project}.\n\nWrite this file to \`${projectSkillPath}\` via a PR.\n\n## Skill Content\n\n\`\`\`\n${enrichedBlock}\n\`\`\``,
+          agentName,
         });
-        if (skillId) {
-          log('info', `Queued work item ${skillId} to PR project skill "${name}" into ${project}`);
+        if (queued && queued.created && queued.workItemId) {
+          log('info', `Queued work item ${queued.workItemId} to PR project skill "${name}" into ${project}`);
         }
       }
     } else {
@@ -3904,93 +3909,84 @@ function updateAgentHistory(agentId, dispatchItem, result) {
   log('info', `Updated history for ${agentId}`);
 }
 
-function reviewFeedbackSourceMatches({ fileName, content, reviewerAgentId, pr, dispatchItem, structuredCompletion }) {
-  if (String(fileName || '').startsWith('feedback-')) return false;
-  const text = String(content || '');
-  const scopedExpected = [
-    dispatchItem?.id,
-    dispatchItem?.meta?.item?.id,
-    structuredCompletion?.dispatchId,
-    pr?.minionsReview?.dispatchId,
-    pr?.minionsReview?.sourceItem,
-  ].filter(Boolean).map(String);
-  if (scopedExpected.length === 0) return true;
-
-  const fileAndContent = `${fileName || ''}\n${text}`;
-  if (!scopedExpected.some(value => fileAndContent.includes(value))) {
-    log('warn', `Skipping review feedback source ${fileName || '(unknown)'} for ${pr?.id || 'unknown PR'}: missing current dispatch/source marker for ${reviewerAgentId}`);
-    return false;
-  }
-
-  const prExpected = [
-    pr?.id,
-    pr?.url,
-  ].filter(Boolean).map(String);
-  if (prExpected.some(value => fileAndContent.includes(value))) return true;
-
-  const prNumber = shared.getPrNumber(pr);
-  if (prNumber != null) {
-    const scope = shared.getPrScopeInfo(pr, pr.url || '')?.scope || shared.getProjectPrScope(dispatchItem?.meta?.project) || '';
-    const numberMention = new RegExp(`(?:#|PR[-\\s])${prNumber}(?!\\d)`, 'i').test(fileAndContent);
-    if (numberMention && (!scope || fileAndContent.toLowerCase().includes(scope.toLowerCase()))) return true;
-  }
-
-  log('warn', `Skipping review feedback source ${fileName || '(unknown)'} for ${pr?.id || 'unknown PR'}: not tied to dispatch/PR scope for ${reviewerAgentId}`);
-  return false;
-}
-
 function createReviewFeedbackForAuthor(reviewerAgentId, pr, config, opts = {}) {
 
-  if (!pr?.id || !pr?.agent) return;
+  if (!pr?.id || !pr?.agent) return null;
   const authorAgentId = pr.agent.toLowerCase();
-  if (!config.agents[authorAgentId]) return;
-  const today = dateStamp();
+  if (!config.agents?.[authorAgentId]) return null;
+  if (opts.reviewVerdict !== REVIEW_STATUS.CHANGES_REQUESTED) return null;
+  if (!features.isFeatureOn('review-learning-capture', config)) return null;
+
   const project = opts.project || opts.dispatchItem?.meta?.project || null;
-  let reviewContent = String(opts.reviewContent || '').trim();
-  if (reviewContent) {
-    if (!reviewContentMatchesPr(reviewContent, pr, project)) {
-      log('warn', `Skipped review feedback for ${pr.id}: review content references a different PR`);
-      return;
-    }
-  } else {
-    const inboxFiles = getInboxFiles();
-    const reviewFiles = inboxFiles.filter(f => f.includes(reviewerAgentId) && f.includes(today));
-    if (reviewFiles.length === 0) return;
-    const matchedReviewContent = [];
-    for (const f of reviewFiles) {
-      const content = safeRead(path.join(INBOX_DIR, f));
-      if (!content) continue;
-      if (!reviewFeedbackSourceMatches({
-        fileName: f,
-        content,
-        reviewerAgentId,
-        pr,
-        dispatchItem: opts.dispatchItem,
-        structuredCompletion: opts.structuredCompletion,
-      })) continue;
-      matchedReviewContent.push(content);
-    }
-    if (matchedReviewContent.length === 0) return;
-    reviewContent = matchedReviewContent.join('\n\n');
-  }
-  const prSlug = shared.safeSlugComponent(pr.id, 60);
-  const content = `# Review Feedback for ${config.agents[authorAgentId]?.name || authorAgentId}\n\n` +
-    `**PR:** ${pr.id} — ${pr.title || ''}\n` +
-    `**Reviewer:** ${config.agents[reviewerAgentId]?.name || reviewerAgentId}\n` +
-    `**Date:** ${today}\n\n` +
-    `## What the reviewer found\n\n${reviewContent}\n\n` +
-    `## Action Required\n\nRead this feedback carefully. When you work on similar tasks in the future, ` +
-    `avoid the patterns flagged here. If you are assigned to fix this PR, ` +
-    `address every point raised above.\n`;
-  shared.writeToInbox('feedback', `${authorAgentId}-from-${reviewerAgentId}-${prSlug}`, content, null, {
-    sourcePr: pr.id,
-    reviewer: reviewerAgentId,
-    author: authorAgentId,
-    dispatchId: opts.dispatchId || opts.dispatchItem?.id || opts.structuredCompletion?.dispatchId || null,
-    sourceItem: opts.sourceItem || opts.dispatchItem?.meta?.item?.id || null,
-    project: project?.name || null,
+  if (!project?.name) {
+    log('warn', `Skipped review-learning candidate for ${pr.id}: project scope is unavailable`);
+    return null;
+  }
+
+  const reviewer = String(reviewerAgentId || '').trim().toLowerCase();
+  const findingIdentity = String(opts.findingIdentity || shared.prReviewFindingIdentity(pr)).trim().toLowerCase();
+  const prId = shared.getCanonicalPrId(project, pr, pr.url || '');
+  const host = String(prId).slice(0, String(prId).indexOf(':')).toLowerCase();
+  const dispatchId = opts.dispatchId || opts.dispatchItem?.id || opts.structuredCompletion?.dispatchId || null;
+  const sourceItem = opts.sourceItem || opts.dispatchItem?.meta?.item?.id || null;
+  const sourceHash = reviewLearning.hashReviewCommentContent(opts.reviewContent || '');
+  const findingKey = reviewLearning.buildFindingKey({
+    project: project.name,
+    prId,
+    sourceKey: `${host}:review-finding:${findingIdentity}`,
+  });
+  const priorCandidate = memoryStore.listMemoryRecords({
+    sourceType: reviewLearning.REVIEW_LEARNING_SOURCE_TYPE,
+    findingKey,
+    limit: 1,
+  })[0] || null;
+  const priorEvents = memoryStore.listMemoryLifecycleEvents({
+    findingKey,
+    limit: 500,
   });
-  log('info', `Created review feedback for ${authorAgentId} from ${reviewerAgentId} on ${pr.id}`);
+  const candidate = reviewLearning.upsertReviewLearningCandidate({
+    findingKey,
+    project: project.name,
+    prId,
+    authorAgent: authorAgentId,
+    reviewerAgent: reviewer,
+    sourceHash,
+    workItemId: sourceItem,
+    dispatchId,
+    metadata: {
+      findingIdentity,
+      postReviewStatus: opts.postReviewStatus || null,
+      reviewVerdict: REVIEW_STATUS.CHANGES_REQUESTED,
+    },
+  });
+  let eventType = 'candidate-created';
+  const hasCreationEvent = priorEvents.some(event => event.eventType === 'candidate-created');
+  const hasCurrentSourceEvent = priorEvents.some(event => (
+    (event.eventType === 'candidate-created' || event.eventType === 'candidate-updated')
+    && event.metadata.sourceHash === candidate.metadata.sourceHash
+  ));
+  if (priorCandidate && hasCreationEvent && candidate.status === 'candidate'
+      && (candidate.metadata.sourceHash !== priorCandidate.metadata.sourceHash || !hasCurrentSourceEvent)) {
+    eventType = 'candidate-updated';
+  }
+  memoryStore.recordMemoryLifecycleEvent({
+    eventType,
+    memoryId: candidate.id,
+    findingKey,
+    project: project.name,
+    agent: authorAgentId,
+    workItemId: candidate.metadata.workItemId || null,
+    dispatchId: candidate.metadata.dispatchId || null,
+    identity: eventType === 'candidate-updated'
+      ? candidate.metadata.sourceHash
+      : (candidate.metadata.findingIdentity || findingIdentity),
+    metadata: {
+      findingIdentity: candidate.metadata.findingIdentity || findingIdentity,
+      sourceHash: candidate.metadata.sourceHash,
+    },
+  });
+  log('info', `Upserted review-learning candidate ${candidate.id} for ${authorAgentId} from ${reviewer} on ${pr.id}`);
+  return candidate;
 }
 
 function updateMetrics(agentId, dispatchItem, result, taskUsage, prsCreatedCount, model) {
@@ -4185,6 +4181,720 @@ function handleInjectionFlag(dispatchItem, agentId, structuredCompletion, config
   return { description, sources, at };
 }
 
+function _canonicalReviewLearningSourceKey(value, host, fallbackKind = 'comment') {
+  if (typeof value !== 'string' || !value.trim() || !host) return null;
+  const raw = value.trim().toLowerCase();
+  const candidates = [raw];
+  if (!raw.startsWith(`${host}:`)) {
+    if (host === 'github' && /^(?:issue|review|review-comment|issue-comment):/.test(raw)) {
+      candidates.push(`${host}:${raw}`);
+    } else if (host === 'ado' && /^\d+:\d+$/.test(raw)) {
+      const [threadId, commentId] = raw.split(':');
+      candidates.push(`${host}:thread:${threadId}:comment:${commentId}`);
+    } else {
+      candidates.push(`${host}:${fallbackKind}:${raw}`);
+    }
+  }
+  for (const candidate of candidates) {
+    try {
+      return reviewLearning.normalizeFindingSourceKey(candidate);
+    } catch {}
+  }
+  return null;
+}
+
+function buildReviewLearningCompletionContext(dispatchItem, agentId) {
+  const meta = dispatchItem?.meta || {};
+  const pr = meta.pr;
+  const project = meta.project;
+  const canonicalPr = shared.getCanonicalPrId(project, pr, pr?.url || '');
+  const prId = reviewLearning.normalizeCanonicalPrId(canonicalPr);
+  const normalizedProject = reviewLearning.normalizeProjectKey(project?.name || meta.item?.project);
+  const authorAgent = pr?.agent && String(pr.agent).toLowerCase() !== 'human'
+    ? pr.agent
+    : (meta.item?.authorAgent || dispatchItem?.agent || agentId);
+  const host = prId.slice(0, prId.indexOf(':'));
+  const allowedSourceKeys = new Set();
+  const addSourceKey = (value, fallbackKind) => {
+    const sourceKey = _canonicalReviewLearningSourceKey(value, host, fallbackKind);
+    if (sourceKey) allowedSourceKeys.add(sourceKey);
+  };
+  const addSourceEntries = (entries) => {
+    if (!Array.isArray(entries)) return;
+    for (const entry of entries) {
+      if (typeof entry === 'string') {
+        addSourceKey(entry);
+        continue;
+      }
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+      addSourceKey(entry.sourceKey || entry.commentKey || entry.key || entry.id);
+    }
+  };
+
+  const findingIds = [
+    meta.reviewFindingId,
+    meta.review_finding_id,
+    pr?.minionsReview ? shared.prReviewFindingIdentity(pr) : null,
+  ].filter(value => typeof value === 'string' && value.trim());
+  for (const findingId of findingIds) addSourceKey(`${host}:review-finding:${findingId}`, 'review-finding');
+
+  addSourceEntries(meta.reviewLearningSourceKeys);
+  addSourceEntries(meta.commentSources);
+  addSourceEntries(meta.item?.meta?.commentSources);
+  addSourceEntries(pr?.humanFeedback?.commentSources);
+  addSourceKey(pr?.humanFeedback?.lastProcessedCommentKey);
+  if (!pr?.humanFeedback?.lastProcessedCommentKey) {
+    addSourceKey(pr?.humanFeedback?.lastProcessedCommentId);
+  }
+
+  return {
+    project: normalizedProject,
+    prId,
+    authorAgent,
+    allowedSourceKeys,
+  };
+}
+
+function suppressReviewLearningCompletionPayload(structuredCompletion) {
+  if (!structuredCompletion || typeof structuredCompletion !== 'object') return;
+  delete structuredCompletion.reviewLearnings;
+  delete structuredCompletion.reviewLearningApplications;
+  delete structuredCompletion._reviewLearningDiagnostics;
+}
+
+function normalizeReviewLearningCompletionPayload(dispatchItem, agentId, structuredCompletion) {
+  const diagnostics = [];
+  if (!structuredCompletion || typeof structuredCompletion !== 'object') {
+    return { structuredCompletion, diagnostics };
+  }
+  const rejectField = (field, err) => {
+    delete structuredCompletion[field];
+    const detail = reviewLearning.redactBoundedText(
+      err?.message || String(err),
+      500,
+      `${field} diagnostic`,
+    );
+    diagnostics.push(`${field} rejected: ${detail || 'invalid payload'}`);
+  };
+
+  if (Object.prototype.hasOwnProperty.call(structuredCompletion, 'reviewLearnings')) {
+    try {
+      const context = buildReviewLearningCompletionContext(dispatchItem, agentId);
+      structuredCompletion.reviewLearnings = reviewLearning.normalizeCompletionReviewLearnings(
+        structuredCompletion.reviewLearnings,
+        context,
+      );
+    } catch (err) {
+      rejectField('reviewLearnings', err);
+    }
+  }
+  if (Object.prototype.hasOwnProperty.call(structuredCompletion, 'reviewLearningApplications')) {
+    try {
+      structuredCompletion.reviewLearningApplications =
+        reviewLearning.normalizeCompletionReviewLearningApplications(
+          structuredCompletion.reviewLearningApplications,
+        );
+    } catch (err) {
+      rejectField('reviewLearningApplications', err);
+    }
+  }
+  if (diagnostics.length) structuredCompletion._reviewLearningDiagnostics = diagnostics;
+  return { structuredCompletion, diagnostics };
+}
+
+function recordReviewLearningCompletionDiagnostics(dispatchItem, agentId, diagnostics) {
+  if (!Array.isArray(diagnostics) || diagnostics.length === 0) return;
+  const messages = diagnostics.slice(0, reviewLearning.REVIEW_LEARNING_BOUNDS.diagnostics)
+    .map(message => reviewLearning.redactBoundedText(
+      message,
+      reviewLearning.REVIEW_LEARNING_BOUNDS.diagnosticBytes,
+      'review-learning completion diagnostic',
+    ));
+  for (const message of messages) {
+    log('warn', `Review-learning completion diagnostic for ${dispatchItem?.id || 'unknown'}: ${message}`);
+  }
+  try {
+    const wiScope = resolveWorkItemScope(dispatchItem?.meta)
+      || dispatchItem?.meta?.project?.name
+      || null;
+    const itemId = dispatchItem?.meta?.item?.id;
+    if (!wiScope || !itemId) return;
+    mutateWorkItems(wiScope, (items) => {
+      if (!Array.isArray(items)) return items;
+      const item = items.find(candidate => candidate.id === itemId);
+      if (item) {
+        const priorMessages = Array.isArray(item._reviewLearningDiagnostics?.messages)
+          ? item._reviewLearningDiagnostics.messages
+          : [];
+        item._reviewLearningDiagnostics = {
+          at: ts(),
+          dispatchId: dispatchItem.id || null,
+          agent: agentId || dispatchItem.agent || null,
+          messages: [...new Set([...priorMessages, ...messages])]
+            .slice(-reviewLearning.REVIEW_LEARNING_BOUNDS.diagnostics),
+        };
+      }
+      return items;
+    });
+  } catch (err) {
+    log('warn', `Could not persist review-learning completion diagnostic: ${err.message}`);
+  }
+}
+
+function _groupReviewLearningEntries(entries) {
+  const groups = new Map();
+  for (const entry of entries) {
+    const findingKey = reviewLearning.buildFindingKey({
+      project: entry.project,
+      prId: entry.source.pr,
+      sourceKey: entry.source.sourceKey,
+    });
+    let group = groups.get(findingKey);
+    if (!group) {
+      group = {
+        findingKey,
+        project: entry.project,
+        prId: entry.source.pr,
+        sourceKey: entry.source.sourceKey,
+        authorAgent: entry.authorAgent,
+        disposition: entry.disposition,
+        audience: entry.applicability,
+        rules: [],
+        files: [],
+        symbols: [],
+        tags: [],
+        evidence: [],
+        confidences: [],
+      };
+      groups.set(findingKey, group);
+    }
+    if (group.disposition !== entry.disposition) {
+      group.error = `review learning source ${entry.source.sourceKey} has conflicting dispositions`;
+    }
+    if (group.audience !== entry.applicability) {
+      group.error = `review learning source ${entry.source.sourceKey} has conflicting audiences`;
+    }
+    group.rules.push(entry.rule);
+    group.files.push(...entry.files);
+    group.symbols.push(...entry.symbols);
+    group.tags.push(...entry.tags);
+    group.evidence.push(...entry.evidence);
+    group.confidences.push(entry.confidence);
+  }
+  return [...groups.values()].map((group) => {
+    const facets = reviewLearning.normalizeReviewFacets(group);
+    return {
+      ...group,
+      rules: [...new Set(group.rules)].sort((a, b) => a.localeCompare(b)),
+      files: facets.files,
+      symbols: facets.symbols,
+      tags: facets.tags,
+      area: facets.area,
+      evidence: [...new Set(group.evidence)].sort((a, b) => a.localeCompare(b)),
+      confidence: Math.min(...group.confidences),
+    };
+  }).sort((a, b) => a.findingKey.localeCompare(b.findingKey));
+}
+
+function _acceptedFixedEvidence(dispatchItem, branchChange, structuredCompletion) {
+  if (shared.isFixLikeWorkType(dispatchItem?.type)
+      && branchChange?.changed === true
+      && branchChange.evidence === 'remote-head'
+      && String(branchChange.afterHead || '').trim()) {
+    return {
+      verifiedBy: 'remote-head',
+      verifiedHeadSha: String(branchChange.afterHead).trim(),
+    };
+  }
+  if (dispatchItem?.type !== WORK_TYPE.REVIEW
+      || reviewVerdictFromCompletion(structuredCompletion) !== REVIEW_STATUS.APPROVED) {
+    return null;
+  }
+  const reviewerAgent = String(dispatchItem?.agent || '').trim().toLowerCase();
+  const authorAgent = String(dispatchItem?.meta?.pr?.agent || '').trim().toLowerCase();
+  if (reviewerAgent && authorAgent && reviewerAgent === authorAgent) return null;
+  const reviewedHeadSha = String(dispatchItem?.meta?.reviewHeadSha || '').trim();
+  const currentHeadSha = getPrFixBaselineHead(dispatchItem?.meta?.pr);
+  if (!reviewedHeadSha || !currentHeadSha || reviewedHeadSha !== currentHeadSha) return null;
+  return { verifiedBy: 'approved-current-head', verifiedHeadSha: currentHeadSha };
+}
+
+function _followUpForReviewSource(sourceKey, followups) {
+  const source = String(sourceKey || '').trim().toLowerCase();
+  const aliases = new Set([source, source.slice(source.lastIndexOf(':') + 1)]);
+  const ado = source.match(/^ado:thread:([^:]+):comment:([^:]+)$/);
+  if (ado) aliases.add(`${ado[1]}:${ado[2]}`);
+  const matches = [];
+  for (const entry of Array.isArray(followups) ? followups : []) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    const parent = String(entry.parent_comment_id ?? entry.parentCommentId ?? '').trim().toLowerCase();
+    const workItemId = String(entry.wi_id ?? entry.wiId ?? '').trim();
+    if (!aliases.has(parent) || !/^[a-z0-9][a-z0-9._:-]{0,319}$/i.test(workItemId)) continue;
+    matches.push({ workItemId, parent });
+  }
+  matches.sort((a, b) => a.workItemId.localeCompare(b.workItemId));
+  return matches[0] || null;
+}
+
+function _captureReviewLearningDiagnostic(result, sourceKey, error) {
+  if (result.diagnostics.length >= reviewLearning.REVIEW_LEARNING_BOUNDS.diagnostics) return;
+  const detail = reviewLearning.redactBoundedText(
+    error?.message || String(error),
+    500,
+    'review-learning capture failure',
+  );
+  const prefix = sourceKey ? `Review-learning capture for ${sourceKey} failed: ` : 'Review-learning capture failed: ';
+  result.diagnostics.push(reviewLearning.redactBoundedText(
+    `${prefix}${detail || 'unknown persistence error'}`,
+    reviewLearning.REVIEW_LEARNING_BOUNDS.diagnosticBytes,
+    'review-learning capture diagnostic',
+  ));
+}
+
+function _surfaceReviewLearningCaptureDiagnostics(
+  dispatchItem,
+  agentId,
+  structuredCompletion,
+  diagnostics,
+) {
+  if (!diagnostics.length) return;
+  structuredCompletion._reviewLearningDiagnostics = [...new Set([
+    ...(Array.isArray(structuredCompletion._reviewLearningDiagnostics)
+      ? structuredCompletion._reviewLearningDiagnostics
+      : []),
+    ...diagnostics,
+  ])].slice(-reviewLearning.REVIEW_LEARNING_BOUNDS.diagnostics);
+  recordReviewLearningCompletionDiagnostics(dispatchItem, agentId, diagnostics);
+}
+
+function _recordReviewLearningCreatedEvent(lesson, group, provenance) {
+  return memoryStore.recordMemoryLifecycleEvent({
+    eventType: 'created',
+    memoryId: lesson.id,
+    findingKey: group.findingKey,
+    project: group.project,
+    agent: group.authorAgent,
+    area: group.area,
+    disposition: group.disposition,
+    identity: lesson.id,
+    metadata: {
+      sourceKey: group.sourceKey,
+      prId: group.prId,
+      audience: group.audience,
+      workItemId: provenance.workItemId,
+      dispatchId: provenance.dispatchId,
+      verifiedBy: provenance.verifiedBy,
+      verifiedHeadSha: provenance.verifiedHeadSha,
+    },
+  });
+}
+
+function _recordRepeatedFindingEvent(lesson, group, match, provenance) {
+  return memoryStore.recordMemoryLifecycleEvent({
+    eventType: 'repeated-finding',
+    memoryId: lesson.id,
+    findingKey: group.findingKey,
+    project: group.project,
+    agent: group.authorAgent,
+    area: group.area,
+    disposition: group.disposition,
+    identity: match.lessonId,
+    metadata: {
+      priorLessonId: match.lessonId,
+      matchReason: match.reason,
+      sourceKey: group.sourceKey,
+      workItemId: provenance.workItemId,
+      dispatchId: provenance.dispatchId,
+    },
+  });
+}
+
+function captureVerifiedReviewLearnings({
+  dispatchItem,
+  agentId,
+  config,
+  structuredCompletion,
+  branchChange,
+  reviewFixResolution,
+} = {}) {
+  const result = { lessons: [], transitions: [], repeated: [], diagnostics: [] };
+  const rawLearnings = structuredCompletion?.reviewLearnings;
+  const supportedType = dispatchItem?.type === WORK_TYPE.REVIEW
+    || shared.isFixLikeWorkType(dispatchItem?.type);
+  if (!supportedType || !Array.isArray(rawLearnings) || rawLearnings.length === 0) return result;
+  if (!features.isFeatureOn('review-learning-capture', config || {})) return result;
+
+  let groups;
+  try {
+    const context = buildReviewLearningCompletionContext(dispatchItem, agentId);
+    // Revalidate at the persistence boundary so future callers cannot bypass source binding.
+    const normalized = reviewLearning.normalizeCompletionReviewLearnings(rawLearnings, context);
+    groups = _groupReviewLearningEntries(normalized);
+  } catch (err) {
+    _captureReviewLearningDiagnostic(result, null, err);
+    _surfaceReviewLearningCaptureDiagnostics(
+      dispatchItem,
+      agentId,
+      structuredCompletion,
+      result.diagnostics,
+    );
+    return result;
+  }
+
+  let priorLessons;
+  try {
+    priorLessons = memoryStore.listActiveReviewLearnings({
+      project: groups[0]?.project,
+      limit: 500,
+    });
+  } catch (err) {
+    _captureReviewLearningDiagnostic(result, null, err);
+    _surfaceReviewLearningCaptureDiagnostics(
+      dispatchItem,
+      agentId,
+      structuredCompletion,
+      result.diagnostics,
+    );
+    return result;
+  }
+  const workItemId = dispatchItem?.meta?.item?.id || null;
+  const dispatchId = dispatchItem?.id || null;
+  const acceptedFixedEvidence = _acceptedFixedEvidence(
+    dispatchItem,
+    branchChange,
+    structuredCompletion,
+  );
+
+  for (const group of groups) {
+    try {
+      if (group.error) throw new TypeError(group.error);
+      const evidence = [...group.evidence];
+      const resolutionFindingId = String(reviewFixResolution?.findingId || '').trim().toLowerCase();
+      const resolutionSourceKey = resolutionFindingId
+        ? `${group.prId.slice(0, group.prId.indexOf(':'))}:review-finding:${resolutionFindingId}`
+        : '';
+      if (resolutionSourceKey === group.sourceKey && reviewFixResolution?.currentCodeEvidence) {
+        evidence.push(String(reviewFixResolution.currentCodeEvidence));
+      }
+      const evidenceKinds = reviewLearning.classifyExactEvidence(evidence);
+      let proof = null;
+      if (group.disposition === reviewLearning.REVIEW_LEARNING_DISPOSITIONS.ACCEPTED_FIXED) {
+        proof = acceptedFixedEvidence;
+        if (!proof) {
+          throw new TypeError('accepted-fixed requires a verified remote branch advancement or approved current head');
+        }
+      } else if (group.disposition === reviewLearning.REVIEW_LEARNING_DISPOSITIONS.SATISFIED_ELSEWHERE) {
+        if (evidenceKinds.length === 0) {
+          throw new TypeError('satisfied-elsewhere requires exact current-code, commit, or test evidence');
+        }
+        proof = { verifiedBy: `exact-${evidenceKinds.join('+')}`, verifiedHeadSha: null };
+      } else if ((group.disposition === reviewLearning.REVIEW_LEARNING_DISPOSITIONS.INVALID
+          || group.disposition === reviewLearning.REVIEW_LEARNING_DISPOSITIONS.STALE)
+          && evidenceKinds.length === 0) {
+        throw new TypeError(`${group.disposition} requires exact trace evidence`);
+      }
+
+      const provenance = {
+        sourceKey: group.sourceKey,
+        workItemId,
+        dispatchId,
+        captureAgent: agentId || dispatchItem?.agent || null,
+        verifiedBy: proof?.verifiedBy || (evidenceKinds.length ? `exact-${evidenceKinds.join('+')}` : 'disposition'),
+        verifiedHeadSha: proof?.verifiedHeadSha || null,
+        evidenceKinds,
+      };
+      const positive = reviewLearning.POSITIVE_DISPOSITIONS.has(group.disposition);
+      if (!positive) {
+        const transitionOptions = {
+          evidence: group.evidence.slice(0, reviewLearning.REVIEW_LEARNING_BOUNDS.transitionEvidence),
+          evidenceKinds,
+          workItemId,
+          dispatchId,
+        };
+        if (group.disposition === reviewLearning.REVIEW_LEARNING_DISPOSITIONS.OUT_OF_SCOPE_FOLLOW_UP) {
+          const followUp = _followUpForReviewSource(group.sourceKey, structuredCompletion.followups);
+          if (!followUp) {
+            throw new TypeError('out-of-scope-follow-up requires a linked follow-up work item');
+          }
+          transitionOptions.followUpWorkItemId = followUp.workItemId;
+          transitionOptions.followUpSourceKey = group.sourceKey;
+          transitionOptions.followUpParentCommentId = followUp.parent;
+        }
+        result.transitions.push(...reviewLearning.transitionReviewLearningCandidate(
+          group.findingKey,
+          group.disposition,
+          transitionOptions,
+        ));
+        continue;
+      }
+
+      const repeatedMatch = reviewLearning.findDeterministicRepeatedLessonMatch(
+        group,
+        priorLessons.filter(record => record.sourceRef !== group.findingKey),
+      );
+      const lesson = reviewLearning.upsertReviewLearningLesson({
+        findingKey: group.findingKey,
+        project: group.project,
+        prId: group.prId,
+        authorAgent: group.authorAgent,
+        audience: group.audience,
+        disposition: group.disposition,
+        rules: group.rules,
+        files: group.files,
+        symbols: group.symbols,
+        tags: group.tags,
+        evidence: group.evidence,
+        confidence: group.confidence,
+        metadata: provenance,
+      });
+      result.lessons.push(lesson);
+      result.transitions.push(...reviewLearning.transitionReviewLearningCandidate(
+        group.findingKey,
+        group.disposition,
+        {
+          lessonId: lesson.id,
+          evidence: group.evidence.slice(0, reviewLearning.REVIEW_LEARNING_BOUNDS.transitionEvidence),
+          evidenceKinds,
+          workItemId,
+          dispatchId,
+          verifiedBy: provenance.verifiedBy,
+          verifiedHeadSha: provenance.verifiedHeadSha,
+        },
+      ));
+      try {
+        _recordReviewLearningCreatedEvent(lesson, group, provenance);
+      } catch (err) {
+        _captureReviewLearningDiagnostic(result, group.sourceKey, err);
+      }
+      if (repeatedMatch) {
+        try {
+          const event = _recordRepeatedFindingEvent(
+            lesson,
+            group,
+            repeatedMatch,
+            provenance,
+          );
+          result.repeated.push(event);
+        } catch (err) {
+          _captureReviewLearningDiagnostic(result, group.sourceKey, err);
+        }
+      }
+    } catch (err) {
+      _captureReviewLearningDiagnostic(result, group.sourceKey, err);
+    }
+  }
+
+  _surfaceReviewLearningCaptureDiagnostics(
+    dispatchItem,
+    agentId,
+    structuredCompletion,
+    result.diagnostics,
+  );
+  return result;
+}
+
+// P-bfc75585 — Application & contradiction lifecycle. Process
+// `reviewLearningApplications` from a completion, but only against lesson IDs
+// this exact dispatch was shown (the trusted retrieval trace) and only for
+// lessons in the dispatch's own project. Emits idempotent applied /
+// considered-not-applicable / contradicted events; an evidence-backed
+// contradiction additionally quarantines the lesson through the retracted
+// lifecycle and raises an operator alert. `considered-not-applicable` and
+// `applied` are task-local and never mutate the lesson.
+function _resolveDispatchProject(dispatchItem) {
+  const meta = dispatchItem?.meta || {};
+  const raw = meta.project?.name || meta.item?.project || '';
+  if (!raw) return '';
+  try {
+    return reviewLearning.normalizeProjectKey(raw);
+  } catch {
+    return '';
+  }
+}
+
+function processReviewLearningApplications({
+  dispatchItem,
+  agentId,
+  config,
+  structuredCompletion,
+} = {}) {
+  const result = {
+    applied: [],
+    notApplicable: [],
+    contradicted: [],
+    retracted: [],
+    diagnostics: [],
+  };
+  const rawApplications = structuredCompletion?.reviewLearningApplications;
+  if (!Array.isArray(rawApplications) || rawApplications.length === 0) return result;
+  // Applications describe how recalled lessons fared, so they are only
+  // meaningful when the recall path is active.
+  if (!features.isFeatureOn('review-learning-recall', config || {})) return result;
+
+  let applications;
+  try {
+    // Revalidate at the persistence boundary so no caller can bypass bounds.
+    applications = reviewLearning.normalizeCompletionReviewLearningApplications(rawApplications);
+  } catch (err) {
+    _captureReviewLearningDiagnostic(result, null, err);
+    _surfaceReviewLearningCaptureDiagnostics(dispatchItem, agentId, structuredCompletion, result.diagnostics);
+    return result;
+  }
+
+  const project = _resolveDispatchProject(dispatchItem);
+  if (!project) {
+    _captureReviewLearningDiagnostic(result, null, new TypeError('review learning applications require a resolved project'));
+    _surfaceReviewLearningCaptureDiagnostics(dispatchItem, agentId, structuredCompletion, result.diagnostics);
+    return result;
+  }
+  const dispatchId = dispatchItem?.id || null;
+  const workItemId = dispatchItem?.meta?.item?.id || null;
+  const applyingAgent = agentId || dispatchItem?.agent || null;
+
+  // Trusted binding: only the lesson IDs actually recalled for THIS dispatch
+  // may be reported on. An agent cannot report application (or trigger a
+  // contradiction) for a lesson it was never shown.
+  const shownIds = new Set();
+  try {
+    const trace = memoryStore.getLatestRetrievalTrace({
+      dispatchId,
+      retrievalKind: 'review-learning',
+      project,
+    });
+    for (const id of trace?.selectedIds || []) shownIds.add(String(id).trim());
+  } catch (err) {
+    _captureReviewLearningDiagnostic(result, null, err);
+  }
+
+  for (const application of applications) {
+    try {
+      if (!shownIds.has(application.id)) {
+        throw new TypeError(`review learning ${application.id} was not shown to this dispatch`);
+      }
+      const lesson = memoryStore.getMemoryRecord(application.id);
+      if (!lesson || lesson.sourceType !== reviewLearning.REVIEW_LEARNING_SOURCE_TYPE) {
+        throw new TypeError(`review learning ${application.id} is not a review-learning record`);
+      }
+      if (lesson.scopeKey !== project) {
+        throw new TypeError(
+          `review learning ${application.id} belongs to project ${lesson.scopeKey}, not ${project}`,
+        );
+      }
+      const findingKey = lesson.sourceRef;
+      const area = lesson.metadata?.area || 'general';
+      const disposition = lesson.metadata?.disposition || null;
+
+      let evidenceKinds = [];
+      if (application.outcome === 'contradicted') {
+        evidenceKinds = reviewLearning.classifyExactEvidence([application.evidence]);
+        if (!evidenceKinds.includes('current-code')) {
+          throw new TypeError('contradicted requires exact current-code evidence');
+        }
+      }
+
+      const event = memoryStore.recordMemoryLifecycleEvent({
+        eventType: application.outcome,
+        memoryId: lesson.id,
+        findingKey,
+        project,
+        agent: applyingAgent,
+        area,
+        disposition,
+        workItemId,
+        dispatchId,
+        identity: lesson.id,
+        metadata: {
+          outcome: application.outcome,
+          evidence: application.evidence,
+          ...(evidenceKinds.length ? { evidenceKinds } : {}),
+        },
+      });
+      if (application.outcome === 'applied') result.applied.push(event);
+      else if (application.outcome === 'considered-not-applicable') result.notApplicable.push(event);
+      else result.contradicted.push(event);
+
+      // Only a scoped, evidence-backed contradiction mutates the lesson:
+      // quarantine it through the retracted lifecycle (provenance retained) and
+      // raise an operator alert. considered-not-applicable / applied leave the
+      // lesson untouched (task-local).
+      if (application.outcome === 'contradicted') {
+        const retraction = memoryStore.retractReviewLearningLesson(lesson.id, {
+          reason: 'contradicted',
+          contradictedBy: applyingAgent,
+          dispatchId,
+          workItemId,
+          evidenceKinds,
+        });
+        const retractedEvent = memoryStore.recordMemoryLifecycleEvent({
+          eventType: 'retracted',
+          memoryId: lesson.id,
+          findingKey,
+          project,
+          agent: applyingAgent,
+          area,
+          disposition,
+          workItemId,
+          dispatchId,
+          identity: lesson.id,
+          metadata: { reason: 'contradicted', evidenceKinds },
+        });
+        result.retracted.push(retractedEvent);
+        if (retraction.changed) {
+          _raiseReviewLearningContradictionAlert({
+            lesson,
+            project,
+            applyingAgent,
+            dispatchItem,
+            evidence: application.evidence,
+            evidenceKinds,
+          });
+        }
+      }
+    } catch (err) {
+      _captureReviewLearningDiagnostic(result, application?.id || null, err);
+    }
+  }
+
+  _surfaceReviewLearningCaptureDiagnostics(dispatchItem, agentId, structuredCompletion, result.diagnostics);
+  return result;
+}
+
+function _raiseReviewLearningContradictionAlert({
+  lesson,
+  project,
+  applyingAgent,
+  dispatchItem,
+  evidence,
+  evidenceKinds,
+} = {}) {
+  try {
+    const detail = reviewLearning.redactBoundedText(
+      evidence || '',
+      reviewLearning.REVIEW_LEARNING_BOUNDS.evidenceBytes,
+      'contradiction evidence',
+    );
+    const lines = [
+      `Review-learning lesson \`${lesson.id}\` was contradicted with exact current-code evidence and quarantined (retracted).`,
+      '',
+      `- Project: ${project}`,
+      `- Finding: ${lesson.sourceRef}`,
+      `- Contradicted by: ${applyingAgent || 'unknown'}`,
+      `- Dispatch: ${dispatchItem?.id || 'unknown'}`,
+      `- Evidence kinds: ${(evidenceKinds || []).join(', ') || 'current-code'}`,
+      `- Evidence: ${detail || '(redacted)'}`,
+      '',
+      'Restoring this lesson is an explicit human action (memory record restore).',
+    ];
+    shared.writeToInbox('engine', `review-learning-contradicted-${lesson.id}`, lines.join('\n'), null, {
+      kind: 'review-learning-contradiction',
+      memoryId: lesson.id,
+      project,
+    });
+  } catch (err) {
+    log('warn', `Could not raise review-learning contradiction alert for ${lesson?.id}: ${err.message}`);
+  }
+}
+
 function parseCompletionReportFile(dispatchItem, opts = {}) {
   const reportPath = dispatchItem?.meta?.completionReportPath || shared.dispatchCompletionReportPath(dispatchItem?.id);
   if (!reportPath || !fs.existsSync(reportPath)) {
@@ -4203,11 +4913,64 @@ function parseCompletionReportFile(dispatchItem, opts = {}) {
     log('warn', `Ignoring completion report without status for ${dispatchItem?.id || 'unknown'}: ${reportPath}`);
     return null;
   }
+  const normalizedStatus = normalizeCompletionStatus(report.status);
+  if (!VALID_COMPLETION_STATUSES.has(normalizedStatus)) {
+    log('warn', `Ignoring completion report with invalid status "${report.status}" for ${dispatchItem?.id || 'unknown'}: ${reportPath}`);
+    return null;
+  }
   report._source = 'report-file';
   report._path = reportPath;
   return report;
 }
 
+function requiredCompletionReportFailure({
+  dispatchId,
+  type,
+  code,
+  structuredCompletion,
+  nonceMismatch,
+  unfinishedToolCall = false,
+  required = true,
+} = {}) {
+  if (
+    !required
+    || code !== 0
+    || nonceMismatch
+    || structuredCompletion
+    || shared.READ_ONLY_ROOT_TASK_TYPES.has(type)
+  ) {
+    return null;
+  }
+  // W-ms0vk9nv000z985b — separate "the runtime turn was truncated" from
+  // "the agent finished but skipped the report".
+  //
+  // `unfinishedToolCall` comes from the dispatch's OWN runtime adapter via the
+  // optional `hasUnfinishedToolCall` hook (engine/runtimes/contract.js): the
+  // adapter is the only component that knows its event vocabulary, so no
+  // runtime-name branching happens here. It is true only when the stream holds
+  // a tool call that was started and never completed — exactly the observed
+  // Copilot case of exiting 0 moments after starting a long `npm test`.
+  //
+  // Deliberately NOT keyed on "the runtime produced no terminal text": a
+  // phantom dispatch (bare `system/init`, garbled stdout) also has no terminal
+  // text but was never truncated mid-work, and must keep the original class.
+  //
+  // Both remain failures: the completion-report contract is NOT weakened. The
+  // truncated case just gets a class that names the real cause, so it is not
+  // mistaken for agent negligence and retry is understood as "re-run the
+  // truncated turn" rather than "the agent will forget the report again".
+  if (unfinishedToolCall) {
+    return {
+      reason: `Runtime for dispatch ${dispatchId || 'unknown'} exited 0 mid-turn: a tool call was started and never completed, and no completion report was written`,
+      failureClass: FAILURE_CLASS.RUNTIME_TRUNCATED_EXIT,
+    };
+  }
+  return {
+    reason: `Required completion report missing or invalid for mutating dispatch ${dispatchId || 'unknown'}`,
+    failureClass: FAILURE_CLASS.COMPLETION_REPORT_MISSING,
+  };
+}
+
 function normalizeCompletionArtifacts(rawArtifacts) {
   let artifacts = rawArtifacts;
   if (typeof artifacts === 'string') {
@@ -4398,6 +5161,18 @@ const NON_TERMINAL_COMPLETION_STATUSES = new Set([
   'blocked', 'incomplete', 'to-be-continued',
   'failed', 'failure', 'error',
 ]);
+const VALID_COMPLETION_STATUSES = new Set([
+  'success', 'succeeded', 'successful', 'done', 'complete', 'completed',
+  ...NON_TERMINAL_COMPLETION_STATUSES,
+]);
+
+// Terminal (clean) success statuses only — VALID_COMPLETION_STATUSES minus the
+// non-terminal (partial/failure) tokens. Used to gate trustedCompletionSuccess so
+// a nonce-verified success report can override a kill-induced nonzero exit
+// (W-mrza78j3001r7a5d).
+const TERMINAL_SUCCESS_COMPLETION_STATUSES = new Set([
+  'success', 'succeeded', 'successful', 'done', 'complete', 'completed',
+]);
 
 function detectNonTerminalResultSummary(_resultSummary, structuredCompletion, completionReport, opts) {
   const candidates = [completionReport?.status, structuredCompletion?.status];
@@ -4685,17 +5460,26 @@ function validateReviewFixCompletion({ type, meta, branchChange, structuredCompl
   const currentCodeEvidence = String(resolution?.currentCodeEvidence || '').trim();
   const hasCurrentCodeReference = /(?:[a-z]:[\\/])?[\w./\\-]+\.[a-z0-9]+:\d+\b/i.test(currentCodeEvidence)
     || /\bcommit\s+[0-9a-f]{7,40}\b/i.test(currentCodeEvidence);
-  const validDisposition = disposition === 'already-resolved' || disposition === 'invalid';
+  let canonicalDisposition = null;
+  try {
+    canonicalDisposition = reviewLearning.normalizeDisposition(disposition);
+  } catch {}
+  const validDisposition = canonicalDisposition === reviewLearning.REVIEW_LEARNING_DISPOSITIONS.SATISFIED_ELSEWHERE
+    || canonicalDisposition === reviewLearning.REVIEW_LEARNING_DISPOSITIONS.INVALID;
   const explicitNoop = !!parseCompletionNoop(structuredCompletion);
 
   if (explicitNoop && validDisposition && reportedFindingId === findingId && hasCurrentCodeReference) {
-    return { valid: true, findingId, resolution };
+    return {
+      valid: true,
+      findingId,
+      resolution: { ...resolution, disposition: canonicalDisposition },
+    };
   }
 
   return {
     valid: false,
     findingId,
-    reason: `Review-fix completion did not advance the PR branch and must explicitly prove the exact finding is already resolved or invalid with current-code evidence. Expected reviewFindingResolution.findingId="${findingId}", disposition "already-resolved" or "invalid", and a file:line or commit reference. Shared platform ownership, viewerDidAuthor, or reviewer/fixer agent equality is not evidence.`,
+    reason: `Review-fix completion did not advance the PR branch and must explicitly prove the exact finding is satisfied elsewhere or invalid with current-code evidence. Expected reviewFindingResolution.findingId="${findingId}", disposition "satisfied-elsewhere" (legacy "already-resolved" is accepted) or "invalid", and a file:line or commit reference. Shared platform ownership, viewerDidAuthor, or reviewer/fixer agent equality is not evidence.`,
   };
 }
 
@@ -4742,33 +5526,6 @@ function extractReviewThreadIds(completion) {
   return Array.from(ids);
 }
 
-function reviewContentMatchesPr(content, pr, project) {
-  const text = String(content || '').trim();
-  if (!text) return false;
-  const targetId = shared.getCanonicalPrId(project, pr, pr?.url || '');
-  const targetNumber = shared.getPrNumber(pr);
-  if (!targetId) return true;
-
-  const explicitRefs = new Set();
-  for (const match of text.matchAll(/\b(?:github|ado):[A-Za-z0-9._~/-]+#\d+\b/g)) {
-    explicitRefs.add(shared.getCanonicalPrId(project, match[0]));
-  }
-  for (const match of text.matchAll(/https?:\/\/[^\s)>"]+(?:\/pull\/|\/pullrequest\/)\d+[^\s)>"]*/gi)) {
-    const url = match[0].replace(/[.,;:]+$/g, '');
-    explicitRefs.add(shared.getCanonicalPrId(project, url, url));
-  }
-  if (explicitRefs.size > 0) return explicitRefs.size === 1 && explicitRefs.has(targetId);
-
-  const mentionedNumbers = new Set();
-  for (const match of text.matchAll(/\bPR\s*(?:#|-)\s*(\d+)\b/gi)) {
-    mentionedNumbers.add(parseInt(match[1], 10));
-  }
-  if (mentionedNumbers.size > 0 && targetNumber != null) {
-    return mentionedNumbers.size === 1 && mentionedNumbers.has(targetNumber);
-  }
-  return true;
-}
-
 function writeNonCleanAgentReport(dispatchItem, agentId, outcome, structuredCompletion, resultSummary, exitCode) {
   if (!dispatchItem?.id || !outcome) {
     log('warn', 'Cannot write non-clean agent report without dispatch id and outcome');
@@ -5439,6 +6196,10 @@ function captureTaskMemoryEpisode(dispatchItem, agentId, outcome, structuredComp
 async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, config, opts) {
 
   const detectPhantom = !!(opts && opts.detectPhantom);
+  const completionReportRequired = !!(opts && opts.completionReportRequired);
+  const preFinalizationFailure = shared.isPlainObject(opts?.preFinalizationFailure)
+    ? opts.preFinalizationFailure
+    : null;
   const type = dispatchItem.type;
   const meta = dispatchItem.meta;
   const isSuccess = code === 0;
@@ -5504,6 +6265,22 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   }
 
   const structuredCompletion = reportCompletion;
+  const completionReportFailure = requiredCompletionReportFailure({
+    dispatchId: dispatchItem.id,
+    type,
+    code,
+    structuredCompletion,
+    nonceMismatch,
+    // W-ms0vk9nv000z985b — did the runtime die between a tool start and its
+    // completion? Answered by THIS dispatch's adapter through the registry
+    // facade, which fails safe to `false` for adapters that don't implement
+    // the hook (so the classification is unchanged for them).
+    unfinishedToolCall: hasUnfinishedToolCall(resolveRuntime(runtimeName), stdout),
+    required: completionReportRequired,
+  });
+  if (completionReportFailure) {
+    log('error', `${completionReportFailure.reason} (agent=${agentId}, exitCode=${code})`);
+  }
   if (structuredCompletion) {
     if (structuredCompletion.summary) resultSummary = String(structuredCompletion.summary);
     log('info', `Structured completion from ${agentId}: status=${structuredCompletion.status}, pr=${structuredCompletion.pr || 'N/A'}${structuredCompletion._source ? ` (${structuredCompletion._source})` : ''}`);
@@ -5530,6 +6307,18 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     if (!structuredCompletion.status || /^(complete|success|done)/i.test(structuredCompletion.status)) {
       structuredCompletion.status = 'failed-injection-flagged';
     }
+    suppressReviewLearningCompletionPayload(structuredCompletion);
+  } else if (structuredCompletion) {
+    const reviewLearningResult = normalizeReviewLearningCompletionPayload(
+      dispatchItem,
+      agentId,
+      structuredCompletion,
+    );
+    recordReviewLearningCompletionDiagnostics(
+      dispatchItem,
+      agentId,
+      reviewLearningResult.diagnostics,
+    );
   }
   const completionGateSummary = resultSummary || (typeof stdout === 'string' && !stdout.includes('"type":') ? stdout : '');
 
@@ -5544,6 +6333,9 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
           branch: dispatchItem.meta?.branch || null,
           sessionId,
           agentsDir: AGENTS_DIR,
+          // W-ms0vk9nv000z985b — anchor the session to the directory it ran in
+          // so a later dispatch can refuse to resume it from a dead worktree.
+          cwd: dispatchItem.worktreePath || null,
           logger: { warn: (msg) => log('warn', msg) },
         });
       }
@@ -5584,7 +6376,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   const benignNoop = nonceMismatch
     ? null
     : classifyBenignZeroTargetOutcome(dispatchItem, structuredCompletion, completionGateSummary);
-  const agentReportedFailure = !!nonceMismatch || (!benignNoop && (
+  const agentReportedFailure = !!nonceMismatch || !!completionReportFailure || !!preFinalizationFailure || (!benignNoop && (
     completionStatus.startsWith('fail')
     || completionStatus === 'error'
     || hasActionableFailureClass(structuredCompletion?.failure_class)
@@ -5602,7 +6394,22 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   if (autoRecovered) {
     log('info', `Auto-recovery: agent failed but created ${prsCreatedCount} PR(s) — upgrading ${meta.item.id} to done`);
   }
-  const effectiveSuccess = !nonceMismatch && (benignNoop || (isSuccess && !agentReportedFailure) || autoRecovered);
+  // W-mrza78j3001r7a5d — trust a nonce-verified TERMINAL-success completion report
+  // even when the process exited nonzero. The legacy stdout-only startup timer used
+  // to `killGracefully` a productive-but-silent runtime, and other kill paths
+  // (steering, spawn-phase watchdog) can also race a valid success report; without
+  // this, `resolveTerminalDispatchResult` privileges the kill-induced nonzero exit
+  // and persists result:error alongside structuredCompletion.status:success. Because
+  // `agentReportedFailure` already folds in nonceMismatch / completionReportFailure /
+  // preFinalizationFailure, this only fires for a clean, trusted success; hard
+  // contract failures are still gated by the resolver's early-returns.
+  const trustedCompletionSuccess = !!structuredCompletion
+    && !agentReportedFailure
+    && TERMINAL_SUCCESS_COMPLETION_STATUSES.has(completionStatus);
+  if (trustedCompletionSuccess && !isSuccess) {
+    log('info', `Trusted completion: nonce-verified success report from ${agentId} overrides process exit code ${code} for ${meta?.item?.id || dispatchItem.id}`);
+  }
+  const effectiveSuccess = !nonceMismatch && (benignNoop || (isSuccess && !agentReportedFailure) || autoRecovered || trustedCompletionSuccess);
   if (!nonceMismatch) {
     const episodeOutcome = effectiveSuccess
       ? (autoRecovered || completionStatus.startsWith('partial') ? 'partial' : 'success')
@@ -5921,7 +6728,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     log('info', `No-op completion for ${meta?.item?.id || dispatchItem.id}: ${noopRationale.slice(0, 200)}`);
   }
 
-  if (effectiveSuccess && meta?.item?.id && !skipDoneStatus && !noopRationale) {
+  if ((effectiveSuccess || completionReportFailure || preFinalizationFailure) && meta?.item?.id && !skipDoneStatus && !noopRationale) {
     completionContractFailure = await enforcePrAttachmentContract(type, meta, agentId, config, resultSummary, stdout, { detectPhantom });
     if (completionContractFailure?.severity === 'hard' || completionContractFailure?.nonTerminal) {
       skipDoneStatus = true;
@@ -5931,7 +6738,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // W-mqsk1ip00006cbae — verify WI PR guard. After enforcePrAttachmentContract
   // (which skips verify types), assert that a verify WI has a PR before
   // allowing the done transition.
-  if (effectiveSuccess && meta?.item?.id && !skipDoneStatus && !noopRationale) {
+  if ((effectiveSuccess || completionReportFailure || preFinalizationFailure) && meta?.item?.id && !skipDoneStatus && !noopRationale) {
     const verifyContractFailure = enforceVerifyPrContract(type, meta, agentId, config, resultSummary);
     if (verifyContractFailure?.severity === 'hard') {
       completionContractFailure = completionContractFailure || verifyContractFailure;
@@ -5939,6 +6746,47 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
     }
   }
 
+  if (completionReportFailure || preFinalizationFailure) skipDoneStatus = true;
+
+  if (effectiveSuccess && !skipDoneStatus && structuredCompletion) {
+    try {
+      captureVerifiedReviewLearnings({
+        dispatchItem,
+        agentId,
+        config,
+        structuredCompletion,
+        branchChange: prFixBranchChange,
+        reviewFixResolution,
+      });
+    } catch (err) {
+      const captureFailure = { diagnostics: [] };
+      _captureReviewLearningDiagnostic(captureFailure, null, err);
+      _surfaceReviewLearningCaptureDiagnostics(
+        dispatchItem,
+        agentId,
+        structuredCompletion,
+        captureFailure.diagnostics,
+      );
+    }
+    try {
+      processReviewLearningApplications({
+        dispatchItem,
+        agentId,
+        config,
+        structuredCompletion,
+      });
+    } catch (err) {
+      const applyFailure = { diagnostics: [] };
+      _captureReviewLearningDiagnostic(applyFailure, null, err);
+      _surfaceReviewLearningCaptureDiagnostics(
+        dispatchItem,
+        agentId,
+        structuredCompletion,
+        applyFailure.diagnostics,
+      );
+    }
+  }
+
   if (effectiveSuccess && meta?.item?.id && !skipDoneStatus) {
     meta._agentId = agentId;
     if (noopRationale) {
@@ -6011,27 +6859,32 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // (engine/lifecycle.js, "_wiMetaForSkip" block) — that way fast-path
   // dispatchers that synthesize meta.qaRunId at the top level keep
   // working too. The agent writes agents/<id>/qa-run-result.json before
-  // exit. Happy path: parse → qaRuns.completeRun({status, summary,
-  // artifacts}). Missing-sidecar path: qaRuns.completeRun({status:
-  // 'errored'}) so the run record always reaches a terminal state and
-  // the dashboard run list never shows a perma-pending row when the
-  // agent crashed before exit.
+  // exit. qa-runs consumes the file exactly once and verifies its runId
+  // before this hook completes the linked record. Missing, malformed, stale,
+  // or invalid-status sidecars terminalize the current run as errored.
   const qaRunId = meta?.qaRunId || meta?.item?.meta?.qaRunId;
-  if (qaRunId) {
+  const lifecycleGateCanRetry = !!(completionReportFailure || preFinalizationFailure)
+    && completionContractFailure?.severity !== 'hard'
+    && completionContractFailure?.nonTerminal !== true
+    && Number(meta?.item?._retryCount || 0) < ENGINE_DEFAULTS.maxRetries;
+  if (qaRunId && lifecycleGateCanRetry) {
+    try { require('./qa-runs').prepareResultSidecar(agentId || '_unknown', qaRunId); }
+    catch (e) { log('warn', `qa-validate deferred sidecar cleanup for ${qaRunId}: ${e.message}`); }
+    log('warn', `qa-validate run ${qaRunId} remains pending while completion validation retries`);
+  } else if (qaRunId) {
     try {
       const qaRuns = require('./qa-runs');
-      const sidecarPath = path.join(AGENTS_DIR, agentId || '_unknown', 'qa-run-result.json');
-      let parsed = null;
-      try {
-        const raw = fs.readFileSync(sidecarPath, 'utf8');
-        parsed = JSON.parse(raw);
-      } catch (e) {
-        if (e.code !== 'ENOENT') {
-          log('warn', `qa-validate sidecar parse for ${qaRunId}: ${e.message}`);
-        }
+      const consumed = qaRuns.consumeResultSidecar(agentId || '_unknown', qaRunId);
+      if (consumed.cleanupError) {
+        log('warn', `qa-validate sidecar cleanup for ${qaRunId}: ${consumed.cleanupError}`);
       }
-      if (parsed && typeof parsed === 'object'
-          && (parsed.status === 'passed' || parsed.status === 'failed')) {
+      const parsed = consumed.ok ? consumed.parsed : null;
+      const sidecarCanComplete = parsed && (
+        effectiveSuccess
+        || parsed.status === qaRuns.QA_RUN_STATUS.FAILED
+        || parsed.status === qaRuns.QA_RUN_STATUS.ERRORED
+      );
+      if (sidecarCanComplete) {
         qaRuns.completeRun(qaRunId, {
           status: parsed.status,
           summary: typeof parsed.summary === 'string' ? parsed.summary : '',
@@ -6039,17 +6892,24 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
         });
         log('info', `qa-validate run ${qaRunId} → ${parsed.status} (${(parsed.artifacts || []).length} artifacts)`);
       } else {
-        // Sidecar missing, malformed, or claims a status outside the
-        // documented enum. Mark run errored so the UI surfaces the failure
-        // and the next dispatcher knows the slot is free.
+        let summary;
+        if (parsed) {
+          summary = 'qa-validate dispatch failed completion validation';
+        } else if (consumed.reason === 'missing') {
+          summary = `qa-validate sidecar missing at ${consumed.filePath}`;
+        } else if (consumed.reason === 'run-id-mismatch') {
+          summary = `qa-validate sidecar runId mismatch (expected ${qaRunId}, got ${consumed.actualRunId || 'missing'})`;
+        } else if (consumed.reason === 'invalid-status') {
+          summary = `qa-validate sidecar malformed (status=${consumed.status})`;
+        } else {
+          summary = `qa-validate sidecar ${consumed.reason} at ${consumed.filePath}${consumed.detail ? `: ${consumed.detail}` : ''}`;
+        }
         qaRuns.completeRun(qaRunId, {
           status: 'errored',
-          summary: parsed
-            ? `qa-validate sidecar malformed (status=${parsed.status})`
-            : `qa-validate sidecar missing at ${sidecarPath}`,
+          summary,
           artifacts: [],
         });
-        log('warn', `qa-validate run ${qaRunId} → errored (sidecar ${parsed ? 'malformed' : 'missing'})`);
+        log('warn', `qa-validate run ${qaRunId} → errored (${parsed ? 'dispatch completion invalid' : `sidecar ${consumed.reason}`})`);
       }
     } catch (err) {
       // qaRuns.completeRun throws on illegal transitions / missing run id.
@@ -6073,7 +6933,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // it under `meta.item.meta`. Accept both.
   const qaSessionId = meta?.sessionId || meta?.item?.meta?.sessionId;
   const qaSessionPhase = meta?.sessionPhase || meta?.item?.meta?.sessionPhase;
-  if (qaSessionId && qaSessionPhase) {
+  if (qaSessionId && qaSessionPhase && !lifecycleGateCanRetry) {
     try {
       const qaSessions = require('./qa-sessions');
       const scope = resolveWorkItemScope(meta);
@@ -6082,13 +6942,16 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
         ? resultSummary
         : '';
       if (qaSessionPhase === 'setup') {
-        qaSessions.handleSetupComplete(qaSessionId, {
-          success: !!effectiveSuccess,
-          scope,
-          project,
-          failureClass: (structuredCompletion && structuredCompletion.failure_class) || null,
-          reason: failureReason,
-        });
+        if (!opts?.deferQaSessionSetup) {
+          handleQaSessionSetupCompletion(meta, {
+            effectiveSuccess,
+            structuredCompletion,
+            resultSummary,
+            scope,
+            project,
+            reason: failureReason,
+          });
+        }
       } else if (qaSessionPhase === 'draft') {
         // The DRAFT agent reports the relative test file path in its
         // structured completion as `testFile` (or the playbook can write a
@@ -6220,7 +7083,8 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   const _skipWorktreeRemovalForAcceptance =
     !!meta?.keep_processes || !!_wiMetaForSkip.keep_processes ||
     !!meta?.managed_spawn || !!_wiMetaForSkip.managed_spawn;
-  if (meta?.branch && meta?.branchStrategy !== 'shared-branch' && !_skipWorktreeRemovalForAcceptance) {
+  const _deferWorktreeRemoval = !!(opts && opts.deferWorktreeRemoval);
+  if (meta?.branch && meta?.branchStrategy !== 'shared-branch' && !_skipWorktreeRemovalForAcceptance && !_deferWorktreeRemoval) {
     try {
       const project = meta.project || {};
       const rootDir = project.localPath ? path.resolve(project.localPath) : null;
@@ -6376,7 +7240,27 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   const metricsResult = isAutoRetry ? 'retry' : finalResult;
   updateMetrics(agentId, dispatchItem, metricsResult, taskUsage, prsCreatedCount, model);
 
-  return { resultSummary, taskUsage, autoRecovered, structuredCompletion, completionContractFailure, agentReportedFailure, agentRetryable, nonceMismatch, benignNoop };
+  return { resultSummary, taskUsage, autoRecovered, trustedCompletionSuccess, structuredCompletion, completionContractFailure, completionReportFailure, preFinalizationFailure, agentReportedFailure, agentRetryable, nonceMismatch, benignNoop, lifecycleGateCanRetry };
+}
+
+function handleQaSessionSetupCompletion(meta, opts = {}) {
+  const qaSessionId = meta?.sessionId || meta?.item?.meta?.sessionId;
+  if (!qaSessionId) return null;
+  const qaSessions = require('./qa-sessions');
+  const scope = opts.scope || resolveWorkItemScope(meta);
+  const project = opts.project !== undefined
+    ? opts.project
+    : (meta?.project?.name || meta?.item?.project || null);
+  const resultSummary = typeof opts.resultSummary === 'string' ? opts.resultSummary : '';
+  return qaSessions.handleSetupCompleteAfterManagedSpawn(qaSessionId, {
+    success: !!opts.effectiveSuccess,
+    scope,
+    project,
+    failureClass: opts.failureClass
+      || (opts.structuredCompletion && opts.structuredCompletion.failure_class)
+      || null,
+    reason: typeof opts.reason === 'string' && opts.reason ? opts.reason : resultSummary,
+  });
 }
 
 // ─── PR → PRD Status Sync ─────────────────────────────────────────────────────
@@ -6640,6 +7524,19 @@ function classifyFailure(code, stdout = '', stderr = '') {
   // Exit code 78 — configuration error (Claude CLI not found, bad setup)
   if (code === 78) return FAILURE_CLASS.CONFIG_ERROR;
 
+  // Stale resumed session (W-ms0vk9nv000z985b). A `--resume`d CLI whose
+  // persisted session or working directory is gone dies before it writes any
+  // stdout, so without this branch the run fell all the way through to the
+  // EMPTY_OUTPUT catch-all — a class that says "the agent produced nothing"
+  // and implies the agent crashed on startup, when in fact the engine handed
+  // it an unusable session id. Checked early: the signal is unambiguous and
+  // the message can otherwise be swallowed by the generic phrase matchers
+  // below. Prevention lives in each adapter's getResumeSessionId; this is the
+  // classification for the residual race.
+  if (shared.isStaleResumeSessionSignal(combined)) {
+    return FAILURE_CLASS.RUNTIME_SESSION_STALE;
+  }
+
   // Max turns exhausted (error_max_turns) — definitive stop reason, retryable
   // Must be checked FIRST — hook startup failures (e.g. curl exit code 28) can inject
   // permission/auth text into stderr, but if the agent ran to turn exhaustion that's the
@@ -7162,9 +8059,11 @@ module.exports = {
   enforceVerifyPrContract,
   markMissingPrAttachment,
   parseCompletionReportFile,
-  // #308 — exported for unit testing: the final non-clean agent note now folds
-  // the grounded harness footprint in as a section instead of emitting a
-  // standalone harness-usage-* inbox note.
+  buildReviewLearningCompletionContext, // exported for testing
+  normalizeReviewLearningCompletionPayload, // exported for testing
+  suppressReviewLearningCompletionPayload, // exported for testing
+  captureVerifiedReviewLearnings, // exported for testing
+  processReviewLearningApplications, // exported for testing
   writeNonCleanAgentReport,
   // exported for testing
   captureTaskMemoryEpisode,
@@ -7172,7 +8071,9 @@ module.exports = {
   completionArtifactToNoteEntry,
   mergeArtifactNotes,
   promoteCompletionArtifacts,
+  requiredCompletionReportFailure, // exported for testing
   runPostCompletionHooks,
+  handleQaSessionSetupCompletion, // exported for testing
   applyGoalInvalidation,
   syncPrdFromPrs,
   advancePrdStatusOnAllItemsDone,