@pellux/goodvibes-sdk 0.33.24 → 0.33.26

package/dist/platform/agents/wrfc-controller.js

@@ -16,7 +16,8 @@ import { runWrfcGateChecks } from './wrfc-gate-runtime.js';
 export { extractScoreFromText, extractPassedFromText, extractIssuesFromText } from './wrfc-reporting.js';
 const VALID_TRANSITIONS = {
     pending: ['engineering'],
-    engineering: ['reviewing', 'failed'],
+    engineering: ['integrating', 'reviewing', 'failed'],
+    integrating: ['reviewing', 'failed'],
     reviewing: ['fixing', 'awaiting_gates', 'failed'],
     fixing: ['reviewing', 'failed'],
     awaiting_gates: ['gating', 'failed'],
@@ -149,10 +150,13 @@ export class WrfcController {
         emitWrfcStateChanged(this.runtimeBus, this.sessionId, chain.id, from, to);
         logger.debug('WrfcController.transition', { chainId: chain.id, from, to });
     }
-    applyWrfcAgentMetadata(chain, record, role) {
+    applyWrfcAgentMetadata(chain, record, role, subtaskId) {
         record.wrfcId = chain.id;
         record.wrfcRole = role;
         record.wrfcPhaseOrder = this.wrfcPhaseOrder(role);
+        if (subtaskId) {
+            record.wrfcSubtaskId = subtaskId;
+        }
         if (role === 'owner') {
             record.progress = this.ownerProgress(chain);
         }
@@ -207,20 +211,28 @@ export class WrfcController {
         });
     }
     ownerProgress(chain) {
+        if (chain.subtasks && chain.subtasks.length > 0) {
+            const passed = chain.subtasks.filter((subtask) => subtask.state === 'passed').length;
+            return `WRFC owner supervising compound chain (${chain.state}, ${passed}/${chain.subtasks.length} deliverables passed)`;
+        }
         return `WRFC owner supervising child agents (${chain.state})`;
     }
     wrfcPhaseOrder(role) {
         switch (role) {
             case 'owner':
                 return 0;
+            case 'orchestrator':
+                return 0;
             case 'engineer':
                 return 1;
             case 'reviewer':
                 return 2;
             case 'fixer':
                 return 3;
-            case 'verifier':
+            case 'integrator':
                 return 4;
+            case 'verifier':
+                return 5;
         }
     }
     setupListeners() {
@@ -264,6 +276,23 @@ export class WrfcController {
             state: chain.state,
             outputLength: rawOutput.length,
         });
+        const subtask = this.findSubtaskByAgentId(chain, agentId);
+        if (subtask) {
+            await this.onCompoundSubtaskAgentComplete(chain, subtask, agentId, rawOutput, record ?? undefined);
+            if (this.planManager) {
+                completePlanItemsForAgent(agentId, this.planManager);
+            }
+            return;
+        }
+        if (agentId === chain.integratorAgentId) {
+            const report = parseEngineerCompletionReport(rawOutput, record?.template);
+            this.setWrfcWorkPlanTaskStatus(chain, agentId, 'done');
+            this.handleIntegratorCompletion(chain, agentId, report);
+            if (this.planManager) {
+                completePlanItemsForAgent(agentId, this.planManager);
+            }
+            return;
+        }
         if (chain.state === 'pending') {
             chain.bufferedCompletion = { agentId, fullOutput: rawOutput };
             logger.debug('WrfcController.onAgentComplete: chain pending, buffering completion', {
@@ -541,6 +570,47 @@ export class WrfcController {
             constraintFailure: unsatisfiedConstraintIds.length > 0,
         };
     }
+    evaluateSubtaskConstraints(subtask, review) {
+        if (subtask.constraints.length === 0) {
+            return {
+                constraintsSatisfied: 0,
+                constraintsTotal: 0,
+                unsatisfiedConstraintIds: [],
+                ignoredConstraintFindingIds: [],
+                constraintFailure: false,
+            };
+        }
+        const expectedIds = new Set(subtask.constraints.map((constraint) => constraint.id));
+        const findingMap = new Map();
+        const ignoredConstraintFindingIds = [];
+        for (const finding of review.constraintFindings ?? []) {
+            if (!expectedIds.has(finding.constraintId)) {
+                ignoredConstraintFindingIds.push(finding.constraintId);
+                continue;
+            }
+            if (!findingMap.has(finding.constraintId)) {
+                findingMap.set(finding.constraintId, finding);
+            }
+        }
+        let constraintsSatisfied = 0;
+        const unsatisfiedConstraintIds = [];
+        for (const constraint of subtask.constraints) {
+            const finding = findingMap.get(constraint.id);
+            if (finding?.satisfied === true) {
+                constraintsSatisfied += 1;
+            }
+            else {
+                unsatisfiedConstraintIds.push(constraint.id);
+            }
+        }
+        return {
+            constraintsSatisfied,
+            constraintsTotal: subtask.constraints.length,
+            unsatisfiedConstraintIds,
+            ignoredConstraintFindingIds,
+            constraintFailure: unsatisfiedConstraintIds.length > 0,
+        };
+    }
     async processGateResults(chain, results) {
         if (!chain.currentNodeId?.includes(':gate:')) {
             chain.currentNodeId = startWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, `gate:${chain.reviewCycles}:${chain.fixAttempts}`, 'verifier', 'Quality gates');
@@ -635,6 +705,7 @@ export class WrfcController {
         const allChains = Array.from(this.chains.values()).filter((chain) => chain.state !== 'passed' && chain.state !== 'failed');
         const activeWorkChains = allChains.filter((chain) => (chain.state === 'pending'
             || chain.state === 'engineering'
+            || chain.state === 'integrating'
             || chain.state === 'reviewing'
             || chain.state === 'fixing'));
         if (activeWorkChains.length > 0) {
@@ -662,11 +733,9 @@ export class WrfcController {
     }
     async autoCommit(chain) {
         this.transition(chain, 'committing');
-        const agentId = chain.allAgentIds.length > 0
-            ? chain.allAgentIds[chain.allAgentIds.length - 1]
-            : (chain.fixerAgentId ?? chain.engineerAgentId);
-        if (!agentId) {
-            this.failChain(chain, 'autoCommit: no agent ID found on chain');
+        const commitCandidateIds = this.autoCommitCandidateAgentIds(chain);
+        if (commitCandidateIds.length === 0) {
+            this.failChain(chain, 'autoCommit: no write-capable WRFC agent found on chain');
             return;
         }
         if (!existsSync(join(this.projectRoot, '.git'))) {
@@ -675,11 +744,29 @@ export class WrfcController {
             return;
         }
         const worktree = this.createWorktree();
+        let completed = false;
         try {
-            const merged = await worktree.merge(agentId);
-            emitWrfcAutoCommitted(this.runtimeBus, this.sessionId, chain.id);
+            const commitMessage = this.autoCommitMessage(chain);
+            const directCommitHash = worktree.commitWorkingTree
+                ? await worktree.commitWorkingTree(commitMessage)
+                : null;
+            let mergedCount = 0;
+            for (const agentId of commitCandidateIds) {
+                if (await worktree.merge(agentId)) {
+                    mergedCount += 1;
+                }
+            }
+            const headHash = mergedCount > 0 && worktree.currentHead ? await worktree.currentHead() : directCommitHash;
+            emitWrfcAutoCommitted(this.runtimeBus, this.sessionId, chain.id, headHash ?? undefined);
             this.completeChainAsPassed(chain);
-            logger.debug('WrfcController.autoCommit: success', { chainId: chain.id, agentId, merged });
+            completed = true;
+            logger.debug('WrfcController.autoCommit: success', {
+                chainId: chain.id,
+                commitCandidateIds,
+                directCommitHash,
+                mergedCount,
+                headHash,
+            });
         }
         catch (error) {
             const reason = summarizeError(error);
@@ -687,7 +774,10 @@ export class WrfcController {
             this.failChain(chain, `autoCommit failed: ${reason}`);
         }
         finally {
-            for (const id of chain.allAgentIds) {
+            const cleanupIds = completed
+                ? chain.allAgentIds
+                : chain.allAgentIds.filter((id) => !commitCandidateIds.includes(id));
+            for (const id of cleanupIds) {
                 worktree.cleanup(id).catch((error) => {
                     logger.warn('WrfcController.autoCommit: cleanup failed', {
                         agentId: id,
@@ -697,12 +787,49 @@ export class WrfcController {
             }
         }
     }
+    autoCommitCandidateAgentIds(chain) {
+        const candidates = [];
+        const add = (agentId) => {
+            if (agentId && !candidates.includes(agentId))
+                candidates.push(agentId);
+        };
+        if (chain.subtasks && chain.subtasks.length > 0) {
+            for (const subtask of chain.subtasks) {
+                add(subtask.fixerAgentId ?? subtask.engineerAgentId);
+            }
+            add(chain.integratorAgentId);
+            return candidates;
+        }
+        add(chain.fixerAgentId ?? chain.engineerAgentId);
+        add(chain.integratorAgentId);
+        if (candidates.length > 0) {
+            return candidates;
+        }
+        const writeRoles = new Set(['engineer', 'fixer', 'integrator']);
+        for (const agentId of chain.allAgentIds) {
+            const recordRole = this.agentManager.getStatus(agentId)?.wrfcRole;
+            const role = recordRole ?? this.workPlanRoleForAgent(chain, agentId);
+            if (role && writeRoles.has(role))
+                add(agentId);
+        }
+        return candidates;
+    }
+    autoCommitMessage(chain) {
+        const firstLine = chain.task.trim().replace(/\s+/g, ' ').slice(0, 72) || chain.id;
+        return `WRFC: ${firstLine}`;
+    }
     failChain(chain, reason) {
         if (chain.state === 'pending') {
             this.chainQueue = this.chainQueue.filter((queued) => queued.record.id !== chain.ownerAgentId);
         }
         const wasActive = chain.state !== 'passed' && chain.state !== 'failed' && chain.state !== 'pending';
         this.failCurrentNode(chain, reason);
+        for (const subtask of chain.subtasks ?? []) {
+            if (subtask.currentNodeId) {
+                failWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, subtask.currentNodeId, reason);
+                subtask.currentNodeId = undefined;
+            }
+        }
         try {
             this.transition(chain, 'failed');
         }
@@ -854,7 +981,26 @@ export class WrfcController {
         failWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, chain.currentNodeId, error);
         chain.currentNodeId = undefined;
     }
+    completeSubtaskNode(chain, subtask, summary) {
+        if (!subtask.currentNodeId)
+            return;
+        completeWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, subtask.currentNodeId, summary);
+        subtask.currentNodeId = undefined;
+    }
     createBaseChain(ownerRecord) {
+        const subtasks = (ownerRecord.wrfcSubtasks ?? [])
+            .filter((task) => typeof task.task === 'string' && task.task.trim().length > 0)
+            .map((task, index) => ({
+            id: `deliverable-${index + 1}`,
+            title: task.task.trim().slice(0, 80),
+            task: task.task.trim(),
+            state: 'pending',
+            fixAttempts: 0,
+            reviewCycles: 0,
+            reviewScores: [],
+            constraints: [],
+            constraintsEnumerated: false,
+        }));
         const chain = {
             id: this.generateWrfcId(),
             state: 'pending',
@@ -869,6 +1015,7 @@ export class WrfcController {
             constraints: [],
             constraintsEnumerated: false,
             createdAt: Date.now(),
+            ...(subtasks.length > 1 ? { subtasks } : {}),
         };
         this.chains.set(chain.id, chain);
         emitWrfcGraphCreated(this.runtimeBus, this.sessionId, chain.id, `WRFC: ${ownerRecord.task}`);
@@ -886,6 +1033,10 @@ export class WrfcController {
         return chain;
     }
     startEngineeringChain(chain, emitCreated) {
+        if (chain.subtasks && chain.subtasks.length > 1) {
+            this.startCompoundEngineeringChain(chain, emitCreated);
+            return;
+        }
         this.activeChainCount += 1;
         this.transition(chain, 'engineering');
         this.setWrfcWorkPlanTaskStatus(chain, chain.ownerAgentId, 'in_progress');
@@ -909,6 +1060,34 @@ export class WrfcController {
         });
         this.upsertWrfcWorkPlanTask(chain, 'engineer', engineerRecord, 'in_progress');
     }
+    startCompoundEngineeringChain(chain, emitCreated) {
+        this.activeChainCount += 1;
+        this.transition(chain, 'engineering');
+        this.setWrfcWorkPlanTaskStatus(chain, chain.ownerAgentId, 'in_progress');
+        if (emitCreated) {
+            emitWrfcChainCreated(this.runtimeBus, this.sessionId, chain.id, chain.task);
+        }
+        this.appendOwnerDecision(chain, 'compound_started', `Compound WRFC owner supervising ${chain.subtasks?.length ?? 0} deliverables under one chain`, { agentId: chain.ownerAgentId });
+        for (const subtask of chain.subtasks ?? []) {
+            subtask.state = 'engineering';
+            const engineerRecord = this.spawnWrfcAgent(chain, 'engineer', 'engineer', this.buildSubtaskEngineerTask(chain, subtask), true, subtask.id);
+            this.applyWrfcAgentMetadata(chain, engineerRecord, 'engineer', subtask.id);
+            subtask.engineerAgentId = engineerRecord.id;
+            chain.allAgentIds.push(engineerRecord.id);
+            this.messageBus.registerAgent({
+                agentId: engineerRecord.id,
+                role: 'engineer',
+                wrfcId: chain.id,
+            });
+            subtask.currentNodeId = startWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, `subtask:${subtask.id}:engineer:0`, 'engineer', `Engineer ${subtask.title}`, engineerRecord.id);
+            this.appendOwnerDecision(chain, 'spawn_engineer', this.withRouteReason(`Start compound WRFC engineer child for ${subtask.id}`, engineerRecord), {
+                agentId: engineerRecord.id,
+                role: 'engineer',
+                record: engineerRecord,
+            });
+            this.upsertWrfcWorkPlanTask(chain, 'engineer', engineerRecord, 'in_progress', subtask.id);
+        }
+    }
     handleEngineerCompletion(chain, agentId, report) {
         let reportForReview = report;
         this.completeCurrentNode(chain, report.summary);
@@ -981,6 +1160,278 @@ export class WrfcController {
         }
         this.startReview(chain, reportForReview);
     }
+    buildSubtaskEngineerTask(chain, subtask) {
+        return [
+            `Compound WRFC engineer task`,
+            `Parent WRFC ask (authoritative whole):`,
+            chain.task,
+            ``,
+            `Sub-deliverable ${subtask.id}:`,
+            subtask.task,
+            ``,
+            `Instructions:`,
+            `1. Implement only this sub-deliverable, but keep the parent ask in mind for compatibility.`,
+            `2. Do not review or verify sibling deliverables. The WRFC owner controls review/fix phases after your output exists.`,
+            `3. Return a structured EngineerReport JSON block.`,
+        ].join('\n');
+    }
+    buildCompoundIntegrationTask(chain) {
+        const subtaskSummaries = (chain.subtasks ?? []).map((subtask) => [
+            `## ${subtask.id}: ${subtask.title}`,
+            `Task: ${subtask.task}`,
+            `Review cycles: ${subtask.reviewCycles}`,
+            `Last score: ${subtask.reviewScores.at(-1) ?? 'n/a'}`,
+            `Engineer summary: ${subtask.engineerReport?.summary ?? '(no summary)'}`,
+            `Reviewer summary: ${subtask.reviewerReport?.summary ?? '(no review)'}`,
+        ].join('\n')).join('\n\n');
+        return [
+            `Compound WRFC integration task`,
+            `Parent WRFC ask (authoritative full scope):`,
+            chain.task,
+            ``,
+            `All sub-deliverables have individually passed review. Integrate them into one coherent final result.`,
+            ``,
+            subtaskSummaries,
+            ``,
+            `Instructions:`,
+            `1. Inspect the current workspace and the sub-deliverable outputs before editing.`,
+            `2. Resolve cross-deliverable API, export, documentation, and test consistency issues.`,
+            `3. Preserve all accepted sub-deliverable behavior; do not start unrelated new work.`,
+            `4. Return a structured EngineerReport JSON block so the final reviewer can inspect integration changes.`,
+        ].join('\n');
+    }
+    findSubtaskByAgentId(chain, agentId) {
+        for (const subtask of chain.subtasks ?? []) {
+            if (subtask.engineerAgentId === agentId
+                || subtask.reviewerAgentId === agentId
+                || subtask.fixerAgentId === agentId) {
+                return subtask;
+            }
+        }
+        return null;
+    }
+    async onCompoundSubtaskAgentComplete(chain, subtask, agentId, rawOutput, record) {
+        if (agentId === subtask.engineerAgentId || agentId === subtask.fixerAgentId) {
+            const report = parseEngineerCompletionReport(rawOutput, record?.template);
+            this.setWrfcWorkPlanTaskStatus(chain, agentId, 'done');
+            this.handleCompoundEngineerCompletion(chain, subtask, agentId, report);
+            return;
+        }
+        if (agentId === subtask.reviewerAgentId) {
+            const review = parseReviewerCompletionReport(chain.id, rawOutput, getWrfcScoreThreshold(this.configManager));
+            subtask.reviewerReport = review;
+            subtask.reviewCycles += 1;
+            this.setWrfcWorkPlanTaskStatus(chain, agentId, 'done');
+            await this.processCompoundSubtaskReview(chain, subtask, review);
+        }
+    }
+    handleCompoundEngineerCompletion(chain, subtask, agentId, report) {
+        let reportForReview = report;
+        this.completeSubtaskNode(chain, subtask, report.summary);
+        if (subtask.state === 'engineering') {
+            subtask.engineerReport = report;
+            this.workmap.append({
+                ts: new Date().toISOString(),
+                wrfcId: chain.id,
+                event: 'engineer_complete',
+                agentId,
+                task: subtask.task,
+                subtaskId: subtask.id,
+            });
+        }
+        const isEngineerReportShape = (r) => r.archetype === 'engineer';
+        if (!subtask.constraintsEnumerated) {
+            subtask.constraints = isEngineerReportShape(report) ? (report.constraints ?? []) : [];
+            subtask.constraintsEnumerated = true;
+        }
+        else if (isEngineerReportShape(report)) {
+            const fixerConstraints = report.constraints ?? [];
+            reportForReview = this.canonicalizeFixerReportConstraints(report, subtask.constraints);
+            if (subtask.constraints.length === 0) {
+                if (fixerConstraints.length > 0) {
+                    logger.warn('WrfcController: ignored compound fixer-invented constraints for unconstrained subtask', {
+                        chainId: chain.id,
+                        subtaskId: subtask.id,
+                        extra: fixerConstraints.map((constraint) => constraint.id),
+                    });
+                }
+            }
+            else {
+                const expectedIds = new Set(subtask.constraints.map((constraint) => constraint.id));
+                const actualIds = new Set(fixerConstraints.map((constraint) => constraint.id));
+                const missing = [...expectedIds].filter((id) => !actualIds.has(id));
+                const extra = [...actualIds].filter((id) => !expectedIds.has(id));
+                if (missing.length > 0 || extra.length > 0) {
+                    const description = `Fixer regressed constraint continuity for ${subtask.id}: missing=[${missing.join(',')}] extra=[${extra.join(',')}]`;
+                    logger.warn('WrfcController: compound fixer constraint-continuity violation', {
+                        chainId: chain.id,
+                        subtaskId: subtask.id,
+                        missing,
+                        extra,
+                    });
+                    subtask.syntheticIssues ??= [];
+                    subtask.syntheticIssues.push({ severity: 'critical', description });
+                }
+            }
+        }
+        else if (subtask.constraints.length > 0) {
+            const description = `Fixer regressed constraint continuity for ${subtask.id}: missing=[${subtask.constraints.map((constraint) => constraint.id).join(',')}] extra=[]`;
+            logger.warn('WrfcController: compound fixer constraint-continuity violation', {
+                chainId: chain.id,
+                subtaskId: subtask.id,
+                missing: subtask.constraints.map((constraint) => constraint.id),
+                extra: [],
+            });
+            subtask.syntheticIssues ??= [];
+            subtask.syntheticIssues.push({ severity: 'critical', description });
+        }
+        subtask.engineerReport = reportForReview;
+        this.startCompoundSubtaskReview(chain, subtask, reportForReview);
+    }
+    startCompoundSubtaskReview(chain, subtask, report) {
+        subtask.state = 'reviewing';
+        let reviewTask = buildReviewTask(chain.id, `Parent WRFC ask:\n${chain.task}\n\nSub-deliverable ${subtask.id}:\n${subtask.task}`, report, getWrfcScoreThreshold(this.configManager), subtask.constraints);
+        if (subtask.syntheticIssues && subtask.syntheticIssues.length > 0) {
+            const syntheticBlock = [
+                `## Synthetic issues from controller`,
+                ``,
+                ...subtask.syntheticIssues.map((issue) => `- [${issue.severity.toUpperCase()}] ${issue.description}`),
+            ].join('\n');
+            reviewTask = syntheticBlock + '\n\n---\n\n' + reviewTask;
+            subtask.syntheticIssues = [];
+        }
+        const reviewerRecord = this.spawnWrfcAgent(chain, 'reviewer', 'reviewer', reviewTask, true, subtask.id);
+        subtask.reviewerAgentId = reviewerRecord.id;
+        this.applyWrfcAgentMetadata(chain, reviewerRecord, 'reviewer', subtask.id);
+        chain.allAgentIds.push(reviewerRecord.id);
+        this.messageBus.registerAgent({
+            agentId: reviewerRecord.id,
+            role: 'reviewer',
+            wrfcId: chain.id,
+        });
+        subtask.currentNodeId = startWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, `subtask:${subtask.id}:review:${subtask.reviewCycles + 1}`, 'reviewer', `Review ${subtask.title}`, reviewerRecord.id);
+        this.appendOwnerDecision(chain, 'spawn_reviewer', this.withRouteReason(`Review compound sub-deliverable ${subtask.id} after engineer output exists`, reviewerRecord), {
+            agentId: reviewerRecord.id,
+            role: 'reviewer',
+            record: reviewerRecord,
+        });
+        this.upsertWrfcWorkPlanTask(chain, 'reviewer', reviewerRecord, 'in_progress', subtask.id);
+    }
+    async processCompoundSubtaskReview(chain, subtask, review) {
+        const threshold = getWrfcScoreThreshold(this.configManager);
+        const constraintEvaluation = this.evaluateSubtaskConstraints(subtask, review);
+        const passed = review.score >= threshold && !constraintEvaluation.constraintFailure;
+        this.completeSubtaskNode(chain, subtask, `Score ${review.score}/10${passed ? ' passed' : ' needs fixes'}`);
+        emitWorkflowReviewCompleted(this.runtimeBus, createWrfcWorkflowContext(this.sessionId, chain.id), {
+            chainId: chain.id,
+            score: review.score,
+            passed,
+            ...(subtask.constraints.length > 0
+                ? {
+                    constraintsSatisfied: constraintEvaluation.constraintsSatisfied,
+                    constraintsTotal: constraintEvaluation.constraintsTotal,
+                    unsatisfiedConstraintIds: constraintEvaluation.unsatisfiedConstraintIds,
+                }
+                : {}),
+        });
+        this.workmap.append({
+            ts: new Date().toISOString(),
+            wrfcId: chain.id,
+            event: 'review_complete',
+            agentId: subtask.reviewerAgentId,
+            score: review.score,
+            passed,
+            subtaskId: subtask.id,
+            issues: review.issues?.slice(0, 10).map((issue) => ({
+                severity: issue.severity,
+                description: issue.description,
+                file: issue.file,
+            })),
+        });
+        subtask.reviewScores.push(review.score);
+        if (passed) {
+            subtask.state = 'passed';
+            this.appendOwnerDecision(chain, 'subtask_review_passed', `Sub-deliverable ${subtask.id} passed review with ${review.score}/10`, {
+                agentId: subtask.reviewerAgentId,
+                role: 'reviewer',
+                reviewScore: review.score,
+            });
+            if ((chain.subtasks ?? []).every((candidate) => candidate.state === 'passed')) {
+                this.startIntegration(chain);
+            }
+            return;
+        }
+        const maxFixAttempts = getWrfcMaxFixAttempts(this.configManager);
+        if (subtask.fixAttempts >= maxFixAttempts) {
+            subtask.state = 'failed';
+            this.failChain(chain, `Sub-deliverable ${subtask.id} review score ${review.score}/10 below threshold ${threshold}/10 after ${subtask.fixAttempts} fix attempt${subtask.fixAttempts !== 1 ? 's' : ''}`);
+            return;
+        }
+        this.appendOwnerDecision(chain, 'subtask_review_failed', `Sub-deliverable ${subtask.id} review did not pass`, {
+            agentId: subtask.reviewerAgentId,
+            role: 'reviewer',
+            reviewScore: review.score,
+        });
+        this.startCompoundSubtaskFix(chain, subtask, review);
+    }
+    startCompoundSubtaskFix(chain, subtask, review) {
+        subtask.fixAttempts += 1;
+        subtask.state = 'fixing';
+        const targetConstraintIds = this.evaluateSubtaskConstraints(subtask, review).unsatisfiedConstraintIds;
+        emitWorkflowFixAttempted(this.runtimeBus, createWrfcWorkflowContext(this.sessionId, chain.id), {
+            chainId: chain.id,
+            attempt: subtask.fixAttempts,
+            maxAttempts: getWrfcMaxFixAttempts(this.configManager),
+            ...(targetConstraintIds.length > 0 ? { targetConstraintIds } : {}),
+        });
+        const fixerRecord = this.spawnWrfcAgent(chain, 'fixer', 'engineer', buildFixTask(chain.id, `Parent WRFC ask:\n${chain.task}\n\nSub-deliverable ${subtask.id}:\n${subtask.task}`, review, getWrfcScoreThreshold(this.configManager), subtask.fixAttempts, subtask.constraints, review.constraintFindings ?? []), true, subtask.id);
+        subtask.fixerAgentId = fixerRecord.id;
+        this.applyWrfcAgentMetadata(chain, fixerRecord, 'fixer', subtask.id);
+        chain.allAgentIds.push(fixerRecord.id);
+        this.messageBus.registerAgent({
+            agentId: fixerRecord.id,
+            role: 'fixer',
+            wrfcId: chain.id,
+        });
+        subtask.currentNodeId = startWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, `subtask:${subtask.id}:fix:${subtask.fixAttempts}`, 'fixer', `Fix ${subtask.title}`, fixerRecord.id);
+        this.appendOwnerDecision(chain, 'spawn_fixer', this.withRouteReason(`Fix compound sub-deliverable ${subtask.id}`, fixerRecord), {
+            agentId: fixerRecord.id,
+            role: 'fixer',
+            record: fixerRecord,
+        });
+        this.upsertWrfcWorkPlanTask(chain, 'fixer', fixerRecord, 'in_progress', subtask.id);
+    }
+    startIntegration(chain) {
+        this.transition(chain, 'integrating');
+        const integratorRecord = this.spawnWrfcAgent(chain, 'integrator', 'integrator', this.buildCompoundIntegrationTask(chain), true);
+        chain.integratorAgentId = integratorRecord.id;
+        this.applyWrfcAgentMetadata(chain, integratorRecord, 'integrator');
+        chain.allAgentIds.push(integratorRecord.id);
+        this.messageBus.registerAgent({
+            agentId: integratorRecord.id,
+            role: 'integrator',
+            wrfcId: chain.id,
+        });
+        chain.currentNodeId = startWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, `integrator:${Date.now()}`, 'integrator', 'Integrate passed deliverables', integratorRecord.id);
+        this.appendOwnerDecision(chain, 'spawn_integrator', this.withRouteReason('Integrate all passed compound WRFC deliverables before final full-scope review', integratorRecord), {
+            agentId: integratorRecord.id,
+            role: 'integrator',
+            record: integratorRecord,
+        });
+        this.upsertWrfcWorkPlanTask(chain, 'integrator', integratorRecord, 'in_progress');
+    }
+    handleIntegratorCompletion(chain, agentId, report) {
+        chain.integratorReport = report;
+        this.completeCurrentNode(chain, report.summary);
+        this.workmap.append({
+            ts: new Date().toISOString(),
+            wrfcId: chain.id,
+            event: 'integrator_complete',
+            agentId,
+            task: chain.task,
+        });
+        this.startReview(chain, report);
+    }
     canonicalizeFixerReportConstraints(report, constraints) {
         const canonical = {
             ...report,
@@ -997,7 +1448,7 @@ export class WrfcController {
         ].join('\n');
         return canonical;
     }
-    spawnWrfcAgent(chain, role, template, task, dangerouslyDisableWrfc) {
+    spawnWrfcAgent(chain, role, template, task, dangerouslyDisableWrfc, subtaskId) {
         const owner = this.agentManager.getStatus(chain.ownerAgentId);
         const selectedRoute = this.selectChildRoute?.({ chain, role, task, ownerAgent: owner }) ?? null;
         const model = selectedRoute?.model ?? owner?.model;
@@ -1016,9 +1467,13 @@ export class WrfcController {
             ...(routing ? { routing } : {}),
             ...(reasoningEffort ? { reasoningEffort } : {}),
             ...(template === 'engineer' ? { systemPromptAddendum: '\n\n---\n\n' + buildEngineerConstraintAddendum() } : {}),
+            ...(template === 'integrator' ? { systemPromptAddendum: '\n\n---\n\n' + buildEngineerConstraintAddendum() } : {}),
             ...(dangerouslyDisableWrfc ? { dangerously_disable_wrfc: true } : {}),
         });
         record.wrfcId = chain.id;
+        if (subtaskId) {
+            record.wrfcSubtaskId = subtaskId;
+        }
         if (selectedRoute?.reason) {
             record.wrfcRouteReason = selectedRoute.reason;
         }
@@ -1075,16 +1530,18 @@ export class WrfcController {
             });
         }
     }
-    upsertWrfcWorkPlanTask(chain, role, record, status) {
+    upsertWrfcWorkPlanTask(chain, role, record, status, subtaskId) {
         if (!this.workPlanService)
             return;
         const taskId = this.workPlanTaskIdForAgent(chain, record.id, role);
         const task = {
             taskId,
-            title: this.workPlanTaskTitle(role, chain.task),
+            title: this.workPlanTaskTitle(role, role === 'owner' ? chain.task : record.task),
             notes: role === 'owner'
                 ? 'WRFC owner chain supervising lifecycle child agents.'
-                : `WRFC ${role} phase for the owner chain.`,
+                : subtaskId
+                    ? `WRFC ${role} phase for compound deliverable ${subtaskId}.`
+                    : `WRFC ${role} phase for the owner chain.`,
             owner: role,
             status,
             source: 'wrfc',
@@ -1097,6 +1554,7 @@ export class WrfcController {
             metadata: {
                 wrfcState: chain.state,
                 agentTemplate: record.template,
+                ...(subtaskId ? { wrfcSubtaskId: subtaskId } : {}),
             },
         };
         this.enqueueWrfcWorkPlanTaskOperation(taskId, async () => {
@@ -1177,6 +1635,16 @@ export class WrfcController {
             return 'reviewer';
         if (agentId === chain.fixerAgentId)
             return 'fixer';
+        if (agentId === chain.integratorAgentId)
+            return 'integrator';
+        for (const subtask of chain.subtasks ?? []) {
+            if (agentId === subtask.engineerAgentId)
+                return 'engineer';
+            if (agentId === subtask.reviewerAgentId)
+                return 'reviewer';
+            if (agentId === subtask.fixerAgentId)
+                return 'fixer';
+        }
         return null;
     }
     workPlanTaskIdForAgent(chain, agentId, role) {

package/dist/platform/agents/wrfc-runtime-events.d.ts

@@ -6,7 +6,7 @@ export type WorkflowContext = {
     traceId: string;
     source: string;
 };
-export type WrfcNodeRole = 'engineer' | 'reviewer' | 'fixer' | 'verifier';
+export type WrfcNodeRole = 'orchestrator' | 'engineer' | 'reviewer' | 'fixer' | 'integrator' | 'verifier';
 export declare function createWrfcWorkflowContext(sessionId: string, chainId: string): WorkflowContext;
 export declare function createWrfcOrchestrationGraphId(chainId: string): string;
 export declare function emitWrfcStateChanged(runtimeBus: RuntimeEventBus, sessionId: string, chainId: string, from: WrfcState, to: WrfcState): void;