@pellux/goodvibes-sdk 0.33.16 → 0.33.18

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

@@ -8,7 +8,7 @@ import { AgentWorktree } from './worktree.js';
 import { completePlanItemsForAgent } from './wrfc-plan-sync.js';
 import { logger } from '../utils/logger.js';
 import { summarizeError } from '../utils/error-display.js';
-import { emitWorkflowChainFailed, emitWorkflowFixAttempted, emitWorkflowReviewCompleted, } from '../runtime/emitters/index.js';
+import { emitAgentCompleted, emitAgentFailed, emitWorkflowChainFailed, emitWorkflowFixAttempted, emitWorkflowReviewCompleted, } from '../runtime/emitters/index.js';
 import { getWrfcAutoCommit, getWrfcMaxFixAttempts, getWrfcScoreThreshold, } from './wrfc-config.js';
 import { buildEngineerConstraintAddendum, } from './wrfc-prompt-addenda.js';
 import { completeWrfcOrchestrationNode, createWrfcWorkflowContext, emitWrfcAutoCommitted, emitWrfcCascadeAbort, emitWrfcChainCreated, emitWrfcChainPassed, emitWrfcConstraintsEnumerated, emitWrfcGraphCreated, emitWrfcStateChanged, failWrfcOrchestrationNode, startWrfcOrchestrationNode, } from './wrfc-runtime-events.js';
@@ -20,7 +20,7 @@ const VALID_TRANSITIONS = {
     reviewing: ['fixing', 'awaiting_gates', 'failed'],
     fixing: ['reviewing', 'failed'],
     awaiting_gates: ['gating', 'failed'],
-    gating: ['passed', 'failed', 'committing'],
+    gating: ['passed', 'failed', 'committing', 'fixing'],
     committing: ['passed', 'failed'],
 };
 const MAX_ACTIVE_CHAINS = 6;
@@ -30,9 +30,6 @@ export class WrfcController {
     chainQueue = [];
     unsubscribers = [];
     activeChainCount = 0;
-    pendingParentChainIds = new Map();
-    /** Constraints to inherit when a gate-retry child chain is created via the pending path. */
-    pendingParentConstraints = new Map();
     sessionId;
     workmap;
     projectRoot;
@@ -42,6 +39,7 @@ export class WrfcController {
     agentManager;
     configManager;
     createWorktree;
+    selectChildRoute;
     constructor(runtimeBus, messageBus, deps) {
         this.runtimeBus = runtimeBus;
         this.messageBus = messageBus;
@@ -49,22 +47,23 @@ export class WrfcController {
         this.configManager = deps.configManager;
         this.projectRoot = deps.projectRoot;
         this.createWorktree = deps.createWorktree ?? (() => new AgentWorktree(this.projectRoot));
+        this.selectChildRoute = deps.selectChildRoute ?? null;
         this.sessionId = crypto.randomUUID().slice(0, 8);
         this.workmap = new WrfcWorkmap(this.projectRoot, this.sessionId, { surfaceRoot: deps.surfaceRoot });
         this.setupListeners();
     }
-    createChain(engineerRecord) {
+    createChain(ownerRecord) {
         logger.info('WrfcController.createChain: called', {
-            agentId: engineerRecord.id,
-            task: engineerRecord.task.slice(0, 60),
+            agentId: ownerRecord.id,
+            task: ownerRecord.task.slice(0, 60),
             activeChainCount: this.activeChainCount,
         });
-        const chain = this.createBaseChain(engineerRecord);
+        const chain = this.createBaseChain(ownerRecord);
         if (this.activeChainCount >= MAX_ACTIVE_CHAINS) {
-            this.chainQueue.push({ record: engineerRecord, queuedAt: Date.now() });
+            this.chainQueue.push({ record: ownerRecord, queuedAt: Date.now() });
             logger.debug('WrfcController.createChain: at cap, queued', {
                 chainId: chain.id,
-                agentId: engineerRecord.id,
+                agentId: ownerRecord.id,
                 activeCount: this.activeChainCount,
                 queueLength: this.chainQueue.length,
             });
@@ -72,7 +71,7 @@ export class WrfcController {
             return chain;
         }
         this.startEngineeringChain(chain, true);
-        logger.debug('WrfcController.createChain', { chainId: chain.id, agentId: engineerRecord.id });
+        logger.debug('WrfcController.createChain', { chainId: chain.id, agentId: ownerRecord.id });
         return chain;
     }
     getSessionId() { return this.sessionId; }
@@ -89,6 +88,39 @@ export class WrfcController {
     }
     getChain(chainId) { return this.chains.get(chainId) ?? null; }
     listChains() { return Array.from(this.chains.values()); }
+    resumeChain(chainId) {
+        const chain = this.chains.get(chainId);
+        if (!chain || chain.state === 'passed' || chain.state === 'failed')
+            return false;
+        if (this.hasRunningChild(chain)) {
+            this.appendOwnerDecision(chain, 'resume_skipped', 'WRFC chain already has an active child agent');
+            return true;
+        }
+        if (chain.state !== 'pending') {
+            this.appendOwnerDecision(chain, 'resume_skipped', `WRFC chain state ${chain.state} cannot be resumed without an active phase result`);
+            return true;
+        }
+        if (this.activeChainCount >= MAX_ACTIVE_CHAINS) {
+            if (!this.chainQueue.some((queued) => queued.record.id === chain.ownerAgentId)) {
+                const owner = this.agentManager.getStatus(chain.ownerAgentId);
+                if (owner)
+                    this.chainQueue.push({ record: owner, queuedAt: Date.now() });
+            }
+            this.appendOwnerDecision(chain, 'resume_skipped', 'WRFC chain is queued because active chain capacity is full');
+            return true;
+        }
+        this.appendOwnerDecision(chain, 'resume_started', 'WRFC owner resumed pending chain');
+        this.startEngineeringChain(chain, false);
+        return true;
+    }
+    resumeAllActiveChains() {
+        let resumed = 0;
+        for (const chain of this.chains.values()) {
+            if (this.resumeChain(chain.id))
+                resumed += 1;
+        }
+        return resumed;
+    }
     dispose() {
         for (const unsub of this.unsubscribers)
             unsub();
@@ -121,12 +153,21 @@ export class WrfcController {
         const unsubError = this.runtimeBus.on('AGENT_FAILED', ({ payload }) => {
             this.onAgentFailed(payload.agentId, payload.error);
         });
-        this.unsubscribers.push(unsubComplete, unsubError);
+        const unsubCancelled = this.runtimeBus.on('AGENT_CANCELLED', ({ payload }) => {
+            this.onAgentCancelled(payload.agentId, payload.reason);
+        });
+        this.unsubscribers.push(unsubComplete, unsubError, unsubCancelled);
     }
     async onAgentComplete(agentId) {
         const chain = this.findChainByAgentId(agentId);
         if (!chain)
             return;
+        if (agentId === chain.ownerAgentId) {
+            if (chain.ownerTerminalEmitted)
+                return;
+            this.failChain(chain, 'WRFC owner agent completed before the chain reached a terminal state');
+            return;
+        }
         const record = this.agentManager.getStatus(agentId);
         const rawOutput = record?.fullOutput ?? '';
         logger.debug('WrfcController.onAgentComplete', {
@@ -165,13 +206,25 @@ export class WrfcController {
         const chain = this.findChainByAgentId(agentId);
         if (!chain)
             return;
+        if (agentId === chain.ownerAgentId && (chain.state === 'passed' || chain.state === 'failed'))
+            return;
         this.failChain(chain, errorMessage ?? `Agent ${agentId} failed`);
     }
+    onAgentCancelled(agentId, reason) {
+        const chain = this.findChainByAgentId(agentId);
+        if (!chain || chain.state === 'passed' || chain.state === 'failed')
+            return;
+        if (agentId === chain.ownerAgentId) {
+            this.cancelChain(chain, reason ?? 'WRFC owner agent cancelled');
+            return;
+        }
+        this.failChain(chain, reason ?? `Agent ${agentId} cancelled`);
+    }
     startReview(chain, report) {
         this.transition(chain, 'reviewing');
         // Prepend any synthetic issues from the controller (e.g. fixer constraint-continuity
         // violations) to the review task body, then clear them so they fire only once.
-        let reviewTask = buildReviewTask(chain.id, report, getWrfcScoreThreshold(this.configManager), chain.constraints);
+        let reviewTask = buildReviewTask(chain.id, chain.task, report, getWrfcScoreThreshold(this.configManager), chain.constraints);
         if (chain.syntheticIssues && chain.syntheticIssues.length > 0) {
             const syntheticBlock = [
                 `## Synthetic issues from controller`,
@@ -181,8 +234,9 @@ export class WrfcController {
             reviewTask = syntheticBlock + '\n\n---\n\n' + reviewTask;
             chain.syntheticIssues = [];
         }
-        const reviewerRecord = this.spawnWrfcAgent(chain, 'reviewer', reviewTask, true);
+        const reviewerRecord = this.spawnWrfcAgent(chain, 'reviewer', 'reviewer', reviewTask, true);
         chain.reviewerAgentId = reviewerRecord.id;
+        reviewerRecord.wrfcRole = 'reviewer';
         chain.allAgentIds.push(reviewerRecord.id);
         reviewerRecord.wrfcId = chain.id;
         this.messageBus.registerAgent({
@@ -195,6 +249,11 @@ export class WrfcController {
             chainId: chain.id,
             reviewerAgentId: reviewerRecord.id,
         });
+        this.appendOwnerDecision(chain, 'spawn_reviewer', this.withRouteReason('Review full current result against the original WRFC ask', reviewerRecord), {
+            agentId: reviewerRecord.id,
+            role: 'reviewer',
+            record: reviewerRecord,
+        });
     }
     async processReview(chain, review) {
         const threshold = getWrfcScoreThreshold(this.configManager);
@@ -249,6 +308,11 @@ export class WrfcController {
         });
         chain.reviewScores.push(review.score);
         if (passed) {
+            this.appendOwnerDecision(chain, 'review_passed', `Review score ${review.score}/10 met threshold ${threshold}/10`, {
+                agentId: chain.reviewerAgentId,
+                role: 'reviewer',
+                reviewScore: review.score,
+            });
             this.transition(chain, 'awaiting_gates');
             await this.checkAndRunGatesForAll();
             return;
@@ -269,6 +333,11 @@ export class WrfcController {
             this.failChain(chain, failureReason);
             return;
         }
+        this.appendOwnerDecision(chain, 'review_failed', `Review score ${review.score}/10 did not pass full-scope WRFC review`, {
+            agentId: chain.reviewerAgentId,
+            role: 'reviewer',
+            reviewScore: review.score,
+        });
         this.startFix(chain, review);
     }
     startFix(chain, review) {
@@ -282,8 +351,9 @@ export class WrfcController {
             maxAttempts,
             ...(targetConstraintIds.length > 0 ? { targetConstraintIds } : {}),
         });
-        const fixerRecord = this.spawnWrfcAgent(chain, 'engineer', buildFixTask(chain.id, review, getWrfcScoreThreshold(this.configManager), chain.fixAttempts, chain.constraints, review.constraintFindings ?? []), true);
+        const fixerRecord = this.spawnWrfcAgent(chain, 'fixer', 'engineer', buildFixTask(chain.id, chain.task, review, getWrfcScoreThreshold(this.configManager), chain.fixAttempts, chain.constraints, review.constraintFindings ?? []), true);
         chain.fixerAgentId = fixerRecord.id;
+        fixerRecord.wrfcRole = 'fixer';
         chain.allAgentIds.push(fixerRecord.id);
         fixerRecord.wrfcId = chain.id;
         this.messageBus.registerAgent({
@@ -304,6 +374,11 @@ export class WrfcController {
             fixerAgentId: fixerRecord.id,
             attempt: chain.fixAttempts,
         });
+        this.appendOwnerDecision(chain, 'spawn_fixer', this.withRouteReason('Fix review findings while preserving the full original WRFC ask', fixerRecord), {
+            agentId: fixerRecord.id,
+            role: 'fixer',
+            record: fixerRecord,
+        });
     }
     async runGates(chain) {
         this.transition(chain, 'gating');
@@ -382,6 +457,7 @@ export class WrfcController {
         if (allPassed) {
             this.workmap.append({ ts: new Date().toISOString(), wrfcId: chain.id, event: 'chain_passed' });
             chain.gatesPassed = true;
+            this.appendOwnerDecision(chain, 'gate_passed', 'All configured WRFC quality gates passed');
             if (autoCommit) {
                 await this.autoCommit(chain);
             }
@@ -391,50 +467,54 @@ export class WrfcController {
             return;
         }
         const failedGates = results.filter((result) => !result.passed);
-        const fingerprint = failedGates.map((result) => `${result.gate}:${result.output.slice(0, 200)}`).join('|');
         const maxGateRetries = getWrfcMaxFixAttempts(this.configManager);
-        chain.gateFailureFingerprint = fingerprint;
-        this.completeChainAsPassed(chain);
-        if (chain.gateRetryDepth >= maxGateRetries) {
+        this.appendOwnerDecision(chain, 'gate_failed', `${failedGates.length} quality gate(s) failed and require same-chain fixing`);
+        if (chain.fixAttempts >= maxGateRetries) {
             logger.error('WrfcController.processGateResults: gate retry limit reached, manual intervention required', {
                 chainId: chain.id,
-                gateRetryDepth: chain.gateRetryDepth,
+                fixAttempts: chain.fixAttempts,
                 maxGateRetries,
             });
-            emitWrfcCascadeAbort(this.runtimeBus, this.sessionId, chain.id, `Gate failures exceeded max retries (${chain.gateRetryDepth}/${maxGateRetries}). Manual intervention required.`);
+            emitWrfcCascadeAbort(this.runtimeBus, this.sessionId, chain.id, `Gate failures exceeded max retries (${chain.fixAttempts}/${maxGateRetries}). Manual intervention required.`);
+            this.failChain(chain, `Gate failures exceeded max retries (${chain.fixAttempts}/${maxGateRetries})`);
             return;
         }
-        const followUpTask = buildGateFailureTask(chain.id, chain.task, failedGates, chain.constraints);
-        const followUpRecord = this.spawnWrfcAgent(chain, 'engineer', followUpTask, false);
-        const followUpChain = this.findChainByAgentId(followUpRecord.id);
-        if (followUpChain) {
-            followUpChain.parentChainId = chain.id;
-            // Inherit constraints from the parent chain as source: 'inherited'. The
-            // inherited list is authoritative; a child engineer that drops or adds ids
-            // surfaces a synthetic review issue instead of changing scope.
-            if (chain.constraints.length > 0) {
-                followUpChain.constraints = chain.constraints.map((c) => ({
-                    id: c.id,
-                    text: c.text,
-                    source: 'inherited',
-                }));
-                followUpChain.constraintsEnumerated = true;
-            }
-        }
-        else {
-            this.pendingParentChainIds.set(followUpRecord.id, chain.id);
-            // Store parent constraints for inheritance when the child chain is registered later.
-            if (chain.constraints.length > 0) {
-                this.pendingParentConstraints.set(followUpRecord.id, chain.constraints.map((c) => ({
-                    id: c.id,
-                    text: c.text,
-                    source: 'inherited',
-                })));
-            }
-        }
-        logger.debug('WrfcController.processGateResults: gate failure — spawned follow-up agent', {
-            parentChainId: chain.id,
-            followUpAgentId: followUpRecord.id,
+        chain.fixAttempts += 1;
+        this.transition(chain, 'fixing');
+        emitWorkflowFixAttempted(this.runtimeBus, createWrfcWorkflowContext(this.sessionId, chain.id), {
+            chainId: chain.id,
+            attempt: chain.fixAttempts,
+            maxAttempts: maxGateRetries,
+            ...(chain.constraints.length > 0 ? { targetConstraintIds: chain.constraints.map((constraint) => constraint.id) } : {}),
+        });
+        const gateFixTask = buildGateFailureTask(chain.id, chain.task, failedGates, chain.constraints);
+        const fixerRecord = this.spawnWrfcAgent(chain, 'fixer', 'engineer', gateFixTask, true);
+        fixerRecord.wrfcRole = 'fixer';
+        chain.fixerAgentId = fixerRecord.id;
+        chain.allAgentIds.push(fixerRecord.id);
+        fixerRecord.wrfcId = chain.id;
+        this.messageBus.registerAgent({
+            agentId: fixerRecord.id,
+            role: 'fixer',
+            wrfcId: chain.id,
+        });
+        chain.currentNodeId = startWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, `fix:${chain.fixAttempts}:gates`, 'fixer', `Gate fix attempt ${chain.fixAttempts}`, fixerRecord.id);
+        this.workmap.append({
+            ts: new Date().toISOString(),
+            wrfcId: chain.id,
+            event: 'fix_started',
+            agentId: fixerRecord.id,
+            attempt: chain.fixAttempts,
+            gate: failedGates.map((gate) => gate.gate).join(', '),
+        });
+        logger.debug('WrfcController.processGateResults: gate failure — spawned same-chain fixer', {
+            chainId: chain.id,
+            fixerAgentId: fixerRecord.id,
+        });
+        this.appendOwnerDecision(chain, 'spawn_gate_fixer', this.withRouteReason('Fix failed quality gates in the same WRFC owner chain', fixerRecord), {
+            agentId: fixerRecord.id,
+            role: 'fixer',
+            record: fixerRecord,
         });
     }
     scheduleChainCleanup(chain) {
@@ -513,7 +593,7 @@ export class WrfcController {
     }
     failChain(chain, reason) {
         if (chain.state === 'pending') {
-            this.chainQueue = this.chainQueue.filter((queued) => queued.record.id !== chain.engineerAgentId);
+            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);
@@ -528,12 +608,69 @@ export class WrfcController {
         }
         chain.error = reason;
         chain.completedAt = Date.now();
+        this.cancelRunningChildren(chain);
+        this.appendOwnerDecision(chain, 'chain_failed', reason, {
+            agentId: chain.ownerAgentId,
+        });
+        this.completeOwnerAgent(chain, 'failed', reason);
         this.workmap.append({ ts: new Date().toISOString(), wrfcId: chain.id, event: 'chain_failed', reason });
         emitWorkflowChainFailed(this.runtimeBus, createWrfcWorkflowContext(this.sessionId, chain.id), { chainId: chain.id, reason });
         logger.error('WrfcController.failChain', { chainId: chain.id, reason });
         this.scheduleChainCleanup(chain);
         this.safeDequeueNext();
     }
+    cancelRunningChildren(chain) {
+        for (const agentId of chain.allAgentIds) {
+            if (agentId === chain.ownerAgentId)
+                continue;
+            const record = this.agentManager.getStatus(agentId);
+            if (record?.status === 'pending' || record?.status === 'running') {
+                this.agentManager.cancel(agentId);
+            }
+        }
+    }
+    hasRunningChild(chain) {
+        return chain.allAgentIds.some((agentId) => {
+            if (agentId === chain.ownerAgentId)
+                return false;
+            const record = this.agentManager.getStatus(agentId);
+            return record?.status === 'pending' || record?.status === 'running';
+        });
+    }
+    cancelChain(chain, reason) {
+        if (chain.state === 'pending') {
+            this.chainQueue = this.chainQueue.filter((queued) => queued.record.id !== chain.ownerAgentId);
+        }
+        const wasActive = chain.state !== 'pending';
+        this.failCurrentNode(chain, reason);
+        try {
+            this.transition(chain, 'failed');
+        }
+        catch {
+            chain.state = 'failed';
+        }
+        if (wasActive) {
+            this.activeChainCount = Math.max(0, this.activeChainCount - 1);
+        }
+        chain.error = reason;
+        chain.completedAt = Date.now();
+        chain.ownerTerminalEmitted = true;
+        this.appendOwnerDecision(chain, 'chain_cancelled', reason, {
+            agentId: chain.ownerAgentId,
+        });
+        const owner = this.agentManager.getStatus(chain.ownerAgentId);
+        if (owner && (owner.status === 'pending' || owner.status === 'running')) {
+            owner.status = 'cancelled';
+            owner.completedAt = Date.now();
+            owner.progress = reason;
+        }
+        this.cancelRunningChildren(chain);
+        this.workmap.append({ ts: new Date().toISOString(), wrfcId: chain.id, event: 'chain_failed', reason });
+        emitWorkflowChainFailed(this.runtimeBus, createWrfcWorkflowContext(this.sessionId, chain.id), { chainId: chain.id, reason });
+        logger.warn('WrfcController.cancelChain', { chainId: chain.id, reason });
+        this.scheduleChainCleanup(chain);
+        this.safeDequeueNext();
+    }
     async dequeueNext() {
         if (this.chainQueue.length === 0 || this.activeChainCount >= MAX_ACTIVE_CHAINS)
             return;
@@ -565,6 +702,38 @@ export class WrfcController {
         return null;
     }
     generateWrfcId() { return `wrfc-${crypto.randomUUID().slice(0, 8)}`; }
+    generateDecisionId() { return `wrfc-decision-${crypto.randomUUID().slice(0, 8)}`; }
+    appendOwnerDecision(chain, action, reason, details = {}) {
+        const record = details.record ?? (details.agentId ? this.agentManager.getStatus(details.agentId) ?? undefined : undefined);
+        const decision = {
+            id: this.generateDecisionId(),
+            ts: new Date().toISOString(),
+            action,
+            state: chain.state,
+            reason,
+            ...(details.agentId ? { agentId: details.agentId } : {}),
+            ...(details.role ? { role: details.role } : {}),
+            ...(record?.model ? { model: record.model } : {}),
+            ...(record?.provider ? { provider: record.provider } : {}),
+            ...(record?.reasoningEffort ? { reasoningEffort: record.reasoningEffort } : {}),
+            ...(typeof details.reviewScore === 'number' ? { reviewScore: details.reviewScore } : {}),
+        };
+        chain.ownerDecisions.push(decision);
+        this.workmap.append({
+            ts: decision.ts,
+            wrfcId: chain.id,
+            event: 'owner_decision',
+            action,
+            state: chain.state,
+            reason,
+            ...(decision.agentId ? { agentId: decision.agentId } : {}),
+            ...(decision.role ? { role: decision.role } : {}),
+            ...(decision.model ? { model: decision.model } : {}),
+            ...(decision.provider ? { provider: decision.provider } : {}),
+            ...(decision.reasoningEffort ? { reasoningEffort: decision.reasoningEffort } : {}),
+            ...(typeof decision.reviewScore === 'number' ? { score: decision.reviewScore } : {}),
+        });
+    }
     completeCurrentNode(chain, summary) {
         if (!chain.currentNodeId)
             return;
@@ -577,63 +746,59 @@ export class WrfcController {
         failWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, chain.currentNodeId, error);
         chain.currentNodeId = undefined;
     }
-    createBaseChain(engineerRecord) {
-        // Inject the engineer constraint addendum before the runner reads the system prompt.
-        // createBaseChain is called synchronously inside manager.spawn() before
-        // executor.runAgent(record), so the field is visible to the runner.
-        engineerRecord.systemPromptAddendum = '\n\n---\n\n' + buildEngineerConstraintAddendum();
+    createBaseChain(ownerRecord) {
         const chain = {
             id: this.generateWrfcId(),
             state: 'pending',
-            task: engineerRecord.task,
-            engineerAgentId: engineerRecord.id,
-            allAgentIds: [engineerRecord.id],
+            task: ownerRecord.task,
+            ownerAgentId: ownerRecord.id,
+            allAgentIds: [ownerRecord.id],
             fixAttempts: 0,
             reviewCycles: 0,
-            gateRetryDepth: 0,
             reviewScores: [],
+            ownerDecisions: [],
+            ownerTerminalEmitted: false,
             constraints: [],
             constraintsEnumerated: false,
             createdAt: Date.now(),
         };
         this.chains.set(chain.id, chain);
-        emitWrfcGraphCreated(this.runtimeBus, this.sessionId, chain.id, `WRFC: ${engineerRecord.task}`);
-        engineerRecord.wrfcId = chain.id;
+        emitWrfcGraphCreated(this.runtimeBus, this.sessionId, chain.id, `WRFC: ${ownerRecord.task}`);
+        ownerRecord.wrfcId = chain.id;
+        ownerRecord.wrfcRole = 'owner';
+        ownerRecord.progress = 'WRFC owner supervising child agents';
         this.messageBus.registerAgent({
-            agentId: engineerRecord.id,
-            template: engineerRecord.template,
+            agentId: ownerRecord.id,
+            template: ownerRecord.template,
             wrfcId: chain.id,
         });
-        this.attachPendingParentChain(chain, engineerRecord.id);
+        this.appendOwnerDecision(chain, 'chain_created', 'WRFC owner created for original ask', {
+            agentId: ownerRecord.id,
+        });
         return chain;
     }
-    attachPendingParentChain(chain, agentId) {
-        const pendingParentId = this.pendingParentChainIds.get(agentId);
-        if (!pendingParentId)
-            return;
-        chain.parentChainId = pendingParentId;
-        const parent = this.chains.get(pendingParentId);
-        if (parent) {
-            chain.gateRetryDepth = parent.gateRetryDepth + (parent.gateFailureFingerprint ? 1 : 0);
-        }
-        this.pendingParentChainIds.delete(agentId);
-        // Inherit constraints from parent when they were queued via the pending path.
-        // The inherited list is authoritative; child output is checked for continuity
-        // on completion instead of being allowed to change scope.
-        const inherited = this.pendingParentConstraints.get(agentId);
-        if (inherited && inherited.length > 0) {
-            chain.constraints = inherited;
-            chain.constraintsEnumerated = true;
-        }
-        this.pendingParentConstraints.delete(agentId);
-    }
     startEngineeringChain(chain, emitCreated) {
         this.activeChainCount += 1;
         this.transition(chain, 'engineering');
-        chain.currentNodeId = startWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, `engineer:${chain.fixAttempts}`, 'engineer', 'Engineer implementation', chain.engineerAgentId);
+        const engineerRecord = this.spawnWrfcAgent(chain, 'engineer', 'engineer', chain.task, true);
+        engineerRecord.wrfcRole = 'engineer';
+        chain.engineerAgentId = engineerRecord.id;
+        chain.allAgentIds.push(engineerRecord.id);
+        engineerRecord.wrfcId = chain.id;
+        this.messageBus.registerAgent({
+            agentId: engineerRecord.id,
+            role: 'engineer',
+            wrfcId: chain.id,
+        });
+        chain.currentNodeId = startWrfcOrchestrationNode(this.runtimeBus, this.sessionId, chain.id, `engineer:${chain.fixAttempts}`, 'engineer', 'Engineer implementation', engineerRecord.id);
         if (emitCreated) {
             emitWrfcChainCreated(this.runtimeBus, this.sessionId, chain.id, chain.task);
         }
+        this.appendOwnerDecision(chain, 'spawn_engineer', this.withRouteReason('Start WRFC implementation child for the original ask', engineerRecord), {
+            agentId: engineerRecord.id,
+            role: 'engineer',
+            record: engineerRecord,
+        });
     }
     handleEngineerCompletion(chain, agentId, report) {
         this.completeCurrentNode(chain, report.summary);
@@ -683,31 +848,82 @@ export class WrfcController {
         }
         this.startReview(chain, report);
     }
-    spawnWrfcAgent(chain, template, task, dangerouslyDisableWrfc) {
-        const sourceAgent = [chain.fixerAgentId, chain.engineerAgentId]
-            .filter((value) => typeof value === 'string')
-            .map((agentId) => this.agentManager.getStatus(agentId))
-            .find((record) => record != null) ?? null;
-        return this.agentManager.spawn({
+    spawnWrfcAgent(chain, role, template, task, dangerouslyDisableWrfc) {
+        const owner = this.agentManager.getStatus(chain.ownerAgentId);
+        const selectedRoute = this.selectChildRoute?.({ chain, role, task, ownerAgent: owner }) ?? null;
+        const model = selectedRoute?.model ?? owner?.model;
+        const provider = selectedRoute?.provider ?? owner?.provider;
+        const fallbackModels = selectedRoute?.fallbackModels ?? owner?.fallbackModels;
+        const routing = selectedRoute?.routing ?? owner?.routing;
+        const reasoningEffort = selectedRoute?.reasoningEffort ?? owner?.reasoningEffort;
+        const record = this.agentManager.spawn({
             mode: 'spawn',
             task,
             template,
-            ...(sourceAgent?.model ? { model: sourceAgent.model } : {}),
-            ...(sourceAgent?.provider ? { provider: sourceAgent.provider } : {}),
-            ...(sourceAgent?.fallbackModels?.length ? { fallbackModels: [...sourceAgent.fallbackModels] } : {}),
-            ...(sourceAgent?.routing ? { routing: sourceAgent.routing } : {}),
-            ...(sourceAgent?.reasoningEffort ? { reasoningEffort: sourceAgent.reasoningEffort } : {}),
+            parentAgentId: chain.ownerAgentId,
+            ...(model ? { model } : {}),
+            ...(provider ? { provider } : {}),
+            ...(fallbackModels?.length ? { fallbackModels: [...fallbackModels] } : {}),
+            ...(routing ? { routing } : {}),
+            ...(reasoningEffort ? { reasoningEffort } : {}),
+            ...(template === 'engineer' ? { systemPromptAddendum: '\n\n---\n\n' + buildEngineerConstraintAddendum() } : {}),
             ...(dangerouslyDisableWrfc ? { dangerously_disable_wrfc: true } : {}),
         });
+        record.wrfcId = chain.id;
+        if (selectedRoute?.reason) {
+            record.wrfcRouteReason = selectedRoute.reason;
+        }
+        return record;
+    }
+    withRouteReason(baseReason, record) {
+        return record.wrfcRouteReason ? `${baseReason}; route: ${record.wrfcRouteReason}` : baseReason;
     }
     completeChainAsPassed(chain) {
         this.activeChainCount = Math.max(0, this.activeChainCount - 1);
         this.transition(chain, 'passed');
         chain.completedAt = Date.now();
+        this.appendOwnerDecision(chain, 'chain_passed', 'WRFC full-scope review and quality gates passed', {
+            agentId: chain.ownerAgentId,
+        });
+        this.completeOwnerAgent(chain, 'completed', `WRFC chain ${chain.id} passed`);
         emitWrfcChainPassed(this.runtimeBus, this.sessionId, chain.id);
         this.scheduleChainCleanup(chain);
         this.safeDequeueNext();
     }
+    completeOwnerAgent(chain, status, message) {
+        if (chain.ownerTerminalEmitted)
+            return;
+        const owner = this.agentManager.getStatus(chain.ownerAgentId);
+        if (!owner)
+            return;
+        owner.status = status;
+        owner.completedAt = Date.now();
+        owner.progress = message;
+        owner.fullOutput = message;
+        chain.ownerTerminalEmitted = true;
+        const context = {
+            sessionId: this.sessionId,
+            traceId: `${this.sessionId}:wrfc-owner:${chain.id}:${status}`,
+            source: 'wrfc-controller',
+            agentId: owner.id,
+        };
+        if (status === 'completed') {
+            emitAgentCompleted(this.runtimeBus, context, {
+                agentId: owner.id,
+                durationMs: Math.max(0, owner.completedAt - owner.startedAt),
+                output: message,
+                toolCallsMade: owner.toolCallCount,
+            });
+        }
+        else {
+            owner.error = message;
+            emitAgentFailed(this.runtimeBus, context, {
+                agentId: owner.id,
+                durationMs: Math.max(0, owner.completedAt - owner.startedAt),
+                error: message,
+            });
+        }
+    }
     safeDequeueNext() {
         this.dequeueNext().catch((error) => {
             logger.error('WrfcController.dequeueNext unhandled error', { error: summarizeError(error) });