agent-relay 3.1.16 → 3.1.18

package/packages/sdk/dist/workflows/runner.js

@@ -86,6 +86,8 @@ export class WorkflowRunner {
     lastIdleLog = new Map();
     /** Tracks last logged activity type per agent to avoid duplicate status lines. */
     lastActivity = new Map();
+    /** Runtime-name lookup for agents participating in supervised owner flows. */
+    supervisedRuntimeAgents = new Map();
     /** Resolved named paths from the top-level `paths` config, keyed by name → absolute directory. */
     resolvedPaths = new Map();
     constructor(options = {}) {
@@ -1094,6 +1096,10 @@ export class WorkflowRunner {
                     const fromShort = msg.from.replace(/-[a-f0-9]{6,}$/, '');
                     const toShort = msg.to.replace(/-[a-f0-9]{6,}$/, '');
                     this.log(`[msg] ${fromShort} → ${toShort}: ${body}`);
+                    const supervision = this.supervisedRuntimeAgents.get(msg.from);
+                    if (supervision?.role === 'owner') {
+                        void this.trajectory?.ownerMonitoringEvent(supervision.stepName, supervision.logicalName, `Messaged ${msg.to}: ${msg.text.slice(0, 120)}`, { to: msg.to, text: msg.text });
+                    }
                 };
                 this.relay.onAgentSpawned = (agent) => {
                     // Skip agents already managed by step execution
@@ -1207,6 +1213,7 @@ export class WorkflowRunner {
             }
             this.lastIdleLog.clear();
             this.lastActivity.clear();
+            this.supervisedRuntimeAgents.clear();
             this.log('Shutting down broker...');
             await this.relay?.shutdown();
             this.relay = undefined;
@@ -1779,10 +1786,26 @@ export class WorkflowRunner {
         if (!rawAgentDef) {
             throw new Error(`Agent "${agentName}" not found in config`);
         }
-        const agentDef = WorkflowRunner.resolveAgentDef(rawAgentDef);
-        const maxRetries = step.retries ?? agentDef.constraints?.retries ?? errorHandling?.maxRetries ?? 0;
+        const specialistDef = WorkflowRunner.resolveAgentDef(rawAgentDef);
+        const usesOwnerFlow = specialistDef.interactive !== false;
+        const ownerDef = usesOwnerFlow ? this.resolveAutoStepOwner(specialistDef, agentMap) : specialistDef;
+        const reviewDef = usesOwnerFlow ? this.resolveAutoReviewAgent(ownerDef, agentMap) : undefined;
+        const supervised = {
+            specialist: specialistDef,
+            owner: ownerDef,
+            reviewer: reviewDef,
+        };
+        const usesDedicatedOwner = usesOwnerFlow && ownerDef.name !== specialistDef.name;
+        const maxRetries = step.retries ??
+            ownerDef.constraints?.retries ??
+            specialistDef.constraints?.retries ??
+            errorHandling?.maxRetries ??
+            0;
         const retryDelay = errorHandling?.retryDelayMs ?? 1000;
-        const timeoutMs = step.timeoutMs ?? agentDef.constraints?.timeoutMs ?? this.currentConfig?.swarm?.timeoutMs;
+        const timeoutMs = step.timeoutMs ??
+            ownerDef.constraints?.timeoutMs ??
+            specialistDef.constraints?.timeoutMs ??
+            this.currentConfig?.swarm?.timeoutMs;
         let lastError;
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             this.checkAborted();
@@ -1807,60 +1830,110 @@ export class WorkflowRunner {
                     updatedAt: new Date().toISOString(),
                 });
                 this.emit({ type: 'step:started', runId, stepName: step.name });
-                this.postToChannel(`**[${step.name}]** Started (agent: ${agentDef.name})`);
-                await this.trajectory?.stepStarted(step, agentDef.name);
+                this.postToChannel(`**[${step.name}]** Started (owner: ${ownerDef.name}, specialist: ${specialistDef.name})`);
+                await this.trajectory?.stepStarted(step, ownerDef.name, {
+                    role: usesDedicatedOwner ? 'owner' : 'specialist',
+                    owner: ownerDef.name,
+                    specialist: specialistDef.name,
+                    reviewer: reviewDef?.name,
+                });
+                if (usesDedicatedOwner) {
+                    await this.trajectory?.stepSupervisionAssigned(step, supervised);
+                }
+                this.emit({
+                    type: 'step:owner-assigned',
+                    runId,
+                    stepName: step.name,
+                    ownerName: ownerDef.name,
+                    specialistName: specialistDef.name,
+                });
                 // Resolve step-output variables (e.g. {{steps.plan.output}}) at execution time
                 const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
                 let resolvedTask = this.interpolateStepTask(step.task ?? '', stepOutputContext);
                 // If this is an interactive agent, append awareness of non-interactive workers
                 // so the lead knows not to message them and to use step output chaining instead
-                if (agentDef.interactive !== false) {
+                if (specialistDef.interactive !== false || ownerDef.interactive !== false) {
                     const nonInteractiveInfo = this.buildNonInteractiveAwareness(agentMap, stepStates);
                     if (nonInteractiveInfo) {
                         resolvedTask += nonInteractiveInfo;
                     }
                 }
-                // Apply step-level workdir override to agent definition if present
-                let effectiveAgentDef = agentDef;
-                if (step.workdir) {
-                    const stepWorkdir = this.resolveStepWorkdir(step);
-                    if (stepWorkdir) {
-                        effectiveAgentDef = { ...agentDef, cwd: stepWorkdir, workdir: undefined };
+                // Apply step-level workdir override to agent definitions if present
+                const applyStepWorkdir = (def) => {
+                    if (step.workdir) {
+                        const stepWorkdir = this.resolveStepWorkdir(step);
+                        if (stepWorkdir) {
+                            return { ...def, cwd: stepWorkdir, workdir: undefined };
+                        }
                     }
+                    return def;
+                };
+                const effectiveSpecialist = applyStepWorkdir(specialistDef);
+                const effectiveOwner = applyStepWorkdir(ownerDef);
+                let specialistOutput;
+                let ownerOutput;
+                let ownerElapsed;
+                if (usesDedicatedOwner) {
+                    const result = await this.executeSupervisedAgentStep(step, { specialist: effectiveSpecialist, owner: effectiveOwner, reviewer: reviewDef }, resolvedTask, timeoutMs);
+                    specialistOutput = result.specialistOutput;
+                    ownerOutput = result.ownerOutput;
+                    ownerElapsed = result.ownerElapsed;
+                }
+                else {
+                    const ownerTask = this.injectStepOwnerContract(step, resolvedTask, effectiveOwner, effectiveSpecialist);
+                    this.log(`[${step.name}] Spawning owner "${effectiveOwner.name}" (cli: ${effectiveOwner.cli})${step.workdir ? ` [workdir: ${step.workdir}]` : ''}`);
+                    const resolvedStep = { ...step, task: ownerTask };
+                    const ownerStartTime = Date.now();
+                    const output = this.executor
+                        ? await this.executor.executeAgentStep(resolvedStep, effectiveOwner, ownerTask, timeoutMs)
+                        : await this.spawnAndWait(effectiveOwner, resolvedStep, timeoutMs);
+                    ownerElapsed = Date.now() - ownerStartTime;
+                    this.log(`[${step.name}] Owner "${effectiveOwner.name}" exited`);
+                    if (usesOwnerFlow) {
+                        this.assertOwnerCompletionMarker(step, output, ownerTask);
+                    }
+                    specialistOutput = output;
+                    ownerOutput = output;
                 }
-                // Spawn agent via AgentRelay
-                this.log(`[${step.name}] Spawning agent "${effectiveAgentDef.name}" (cli: ${effectiveAgentDef.cli})${step.workdir ? ` [workdir: ${step.workdir}]` : ''}`);
-                const resolvedStep = { ...step, task: resolvedTask };
-                const output = this.executor
-                    ? await this.executor.executeAgentStep(resolvedStep, effectiveAgentDef, resolvedTask, timeoutMs)
-                    : await this.spawnAndWait(effectiveAgentDef, resolvedStep, timeoutMs);
-                this.log(`[${step.name}] Agent "${agentDef.name}" exited`);
                 // Run verification if configured
                 if (step.verification) {
-                    this.runVerification(step.verification, output, step.name, resolvedTask);
+                    this.runVerification(step.verification, specialistOutput, step.name, resolvedTask);
+                }
+                // Every interactive step gets a review pass; pick a dedicated reviewer when available.
+                let combinedOutput = specialistOutput;
+                if (usesOwnerFlow && reviewDef) {
+                    const remainingMs = timeoutMs ? Math.max(0, timeoutMs - ownerElapsed) : undefined;
+                    const reviewOutput = await this.runStepReviewGate(step, resolvedTask, specialistOutput, ownerOutput, ownerDef, reviewDef, remainingMs);
+                    combinedOutput = this.combineStepAndReviewOutput(specialistOutput, reviewOutput);
                 }
                 // Mark completed
                 state.row.status = 'completed';
-                state.row.output = output;
+                state.row.output = combinedOutput;
                 state.row.completedAt = new Date().toISOString();
                 await this.db.updateStep(state.row.id, {
                     status: 'completed',
-                    output,
+                    output: combinedOutput,
                     completedAt: state.row.completedAt,
                     updatedAt: new Date().toISOString(),
                 });
                 // Persist step output to disk so it survives restarts and is inspectable
-                await this.persistStepOutput(runId, step.name, output);
-                this.emit({ type: 'step:completed', runId, stepName: step.name, output });
-                await this.trajectory?.stepCompleted(step, output, attempt + 1);
+                await this.persistStepOutput(runId, step.name, combinedOutput);
+                this.emit({ type: 'step:completed', runId, stepName: step.name, output: combinedOutput });
+                await this.trajectory?.stepCompleted(step, combinedOutput, attempt + 1);
                 return;
             }
             catch (err) {
                 lastError = err instanceof Error ? err.message : String(err);
+                const ownerTimedOut = usesDedicatedOwner
+                    ? /\bowner timed out\b/i.test(lastError)
+                    : /\btimed out\b/i.test(lastError) && !lastError.includes(`${step.name}-review`);
+                if (ownerTimedOut) {
+                    this.emit({ type: 'step:owner-timeout', runId, stepName: step.name, ownerName: ownerDef.name });
+                }
             }
         }
         // All retries exhausted — record root-cause diagnosis and mark failed
-        const nonInteractive = agentDef.interactive === false || ['worker', 'reviewer', 'analyst'].includes(agentDef.preset ?? '');
+        const nonInteractive = ownerDef.interactive === false || ['worker', 'reviewer', 'analyst'].includes(ownerDef.preset ?? '');
         const verificationValue = typeof step.verification === 'object' && 'value' in step.verification
             ? String(step.verification.value)
             : undefined;
@@ -1873,6 +1946,438 @@ export class WorkflowRunner {
         await this.markStepFailed(state, lastError ?? 'Unknown error', runId);
         throw new Error(`Step "${step.name}" failed after ${maxRetries} retries: ${lastError ?? 'Unknown error'}`);
     }
+    injectStepOwnerContract(step, resolvedTask, ownerDef, specialistDef) {
+        if (ownerDef.interactive === false)
+            return resolvedTask;
+        const specialistNote = ownerDef.name === specialistDef.name
+            ? ''
+            : `Specialist intended for this step: "${specialistDef.name}" (${specialistDef.role ?? specialistDef.cli}).`;
+        return (resolvedTask +
+            '\n\n---\n' +
+            `STEP OWNER CONTRACT:\n` +
+            `- You are the accountable owner for step "${step.name}".\n` +
+            (specialistNote ? `- ${specialistNote}\n` : '') +
+            `- If you delegate, you must still verify completion yourself.\n` +
+            `- Before exiting, provide an explicit completion line: STEP_COMPLETE:${step.name}\n` +
+            `- Then self-terminate immediately with /exit.`);
+    }
+    buildOwnerSupervisorTask(step, originalTask, supervised, workerRuntimeName) {
+        const verificationGuide = this.buildSupervisorVerificationGuide(step.verification);
+        const channelLine = this.channel ? `#${this.channel}` : '(workflow channel unavailable)';
+        return (`You are the step owner/supervisor for step "${step.name}".\n\n` +
+            `Worker: ${supervised.specialist.name} (runtime: ${workerRuntimeName}) on ${channelLine}\n` +
+            `Task: ${originalTask}\n\n` +
+            `Your job: Monitor the worker and determine when the task is complete.\n\n` +
+            `How to verify completion:\n` +
+            `- Watch ${channelLine} for the worker's progress messages and mirrored PTY output\n` +
+            `- Check file changes: run \`git diff --stat\` or inspect expected files directly\n` +
+            `- Ask the worker directly on ${channelLine} if you need a status update\n` +
+            verificationGuide +
+            `\nWhen you're satisfied the work is done correctly:\n` +
+            `Output exactly: STEP_COMPLETE:${step.name}`);
+    }
+    buildSupervisorVerificationGuide(verification) {
+        if (!verification)
+            return '';
+        switch (verification.type) {
+            case 'output_contains':
+                return `- Verification gate: confirm the worker output contains ${JSON.stringify(verification.value)}\n`;
+            case 'file_exists':
+                return `- Verification gate: confirm the file exists at ${JSON.stringify(verification.value)}\n`;
+            case 'exit_code':
+                return `- Verification gate: confirm the worker exits with code ${JSON.stringify(verification.value)}\n`;
+            case 'custom':
+                return `- Verification gate: apply the custom verification rule ${JSON.stringify(verification.value)}\n`;
+            default:
+                return '';
+        }
+    }
+    async executeSupervisedAgentStep(step, supervised, resolvedTask, timeoutMs) {
+        if (this.executor) {
+            const supervisorTask = this.buildOwnerSupervisorTask(step, resolvedTask, supervised, supervised.specialist.name);
+            const specialistStep = { ...step, task: resolvedTask };
+            const ownerStep = {
+                ...step,
+                name: `${step.name}-owner`,
+                agent: supervised.owner.name,
+                task: supervisorTask,
+            };
+            this.log(`[${step.name}] Spawning specialist "${supervised.specialist.name}" and owner "${supervised.owner.name}"`);
+            const specialistPromise = this.executor.executeAgentStep(specialistStep, supervised.specialist, resolvedTask, timeoutMs);
+            // Guard against unhandled rejection if owner fails before specialist settles
+            const specialistSettled = specialistPromise.catch(() => undefined);
+            try {
+                const ownerStartTime = Date.now();
+                const ownerOutput = await this.executor.executeAgentStep(ownerStep, supervised.owner, supervisorTask, timeoutMs);
+                const ownerElapsed = Date.now() - ownerStartTime;
+                this.assertOwnerCompletionMarker(step, ownerOutput, supervisorTask);
+                const specialistOutput = await specialistPromise;
+                return { specialistOutput, ownerOutput, ownerElapsed };
+            }
+            catch (error) {
+                await specialistSettled;
+                throw error;
+            }
+        }
+        let workerHandle;
+        let workerRuntimeName = supervised.specialist.name;
+        let workerSpawned = false;
+        let workerReleased = false;
+        let resolveWorkerSpawn;
+        let rejectWorkerSpawn;
+        const workerReady = new Promise((resolve, reject) => {
+            resolveWorkerSpawn = resolve;
+            rejectWorkerSpawn = reject;
+        });
+        const specialistStep = { ...step, task: resolvedTask };
+        this.log(`[${step.name}] Spawning specialist "${supervised.specialist.name}" (cli: ${supervised.specialist.cli})`);
+        const workerPromise = this.spawnAndWait(supervised.specialist, specialistStep, timeoutMs, {
+            agentNameSuffix: 'worker',
+            onSpawned: ({ actualName, agent }) => {
+                workerHandle = agent;
+                workerRuntimeName = actualName;
+                this.supervisedRuntimeAgents.set(actualName, {
+                    stepName: step.name,
+                    role: 'specialist',
+                    logicalName: supervised.specialist.name,
+                });
+                if (!workerSpawned) {
+                    workerSpawned = true;
+                    resolveWorkerSpawn();
+                }
+            },
+            onChunk: ({ agentName, chunk }) => {
+                this.forwardAgentChunkToChannel(step.name, 'Worker', agentName, chunk);
+            },
+        }).catch((error) => {
+            if (!workerSpawned) {
+                workerSpawned = true;
+                rejectWorkerSpawn(error);
+            }
+            throw error;
+        });
+        const workerSettled = workerPromise.catch(() => undefined);
+        workerPromise
+            .then((output) => {
+            workerReleased = true;
+            this.postToChannel(`**[${step.name}]** Worker \`${workerRuntimeName}\` exited`);
+            if (step.verification?.type === 'output_contains' && output.includes(step.verification.value)) {
+                this.postToChannel(`**[${step.name}]** Verification gate observed: output contains ${JSON.stringify(step.verification.value)}`);
+            }
+        })
+            .catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            this.postToChannel(`**[${step.name}]** Worker \`${workerRuntimeName}\` exited with error: ${message}`);
+        });
+        await workerReady;
+        const supervisorTask = this.buildOwnerSupervisorTask(step, resolvedTask, supervised, workerRuntimeName);
+        const ownerStep = {
+            ...step,
+            name: `${step.name}-owner`,
+            agent: supervised.owner.name,
+            task: supervisorTask,
+        };
+        this.log(`[${step.name}] Spawning owner "${supervised.owner.name}" (cli: ${supervised.owner.cli})`);
+        const ownerStartTime = Date.now();
+        try {
+            const ownerOutput = await this.spawnAndWait(supervised.owner, ownerStep, timeoutMs, {
+                agentNameSuffix: 'owner',
+                onSpawned: ({ actualName }) => {
+                    this.supervisedRuntimeAgents.set(actualName, {
+                        stepName: step.name,
+                        role: 'owner',
+                        logicalName: supervised.owner.name,
+                    });
+                },
+                onChunk: ({ chunk }) => {
+                    void this.recordOwnerMonitoringChunk(step, supervised.owner, chunk);
+                },
+            });
+            const ownerElapsed = Date.now() - ownerStartTime;
+            this.log(`[${step.name}] Owner "${supervised.owner.name}" exited`);
+            this.assertOwnerCompletionMarker(step, ownerOutput, supervisorTask);
+            const specialistOutput = await workerPromise;
+            return { specialistOutput, ownerOutput, ownerElapsed };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (!workerReleased && workerHandle) {
+                await workerHandle.release().catch(() => undefined);
+            }
+            await workerSettled;
+            if (/\btimed out\b/i.test(message)) {
+                throw new Error(`Step "${step.name}" owner timed out after ${timeoutMs ?? 'unknown'}ms`);
+            }
+            throw error;
+        }
+    }
+    forwardAgentChunkToChannel(stepName, roleLabel, agentName, chunk) {
+        const lines = WorkflowRunner.stripAnsi(chunk)
+            .split('\n')
+            .map((line) => line.trim())
+            .filter(Boolean)
+            .slice(0, 3);
+        for (const line of lines) {
+            this.postToChannel(`**[${stepName}]** ${roleLabel} \`${agentName}\`: ${line.slice(0, 280)}`);
+        }
+    }
+    async recordOwnerMonitoringChunk(step, ownerDef, chunk) {
+        const stripped = WorkflowRunner.stripAnsi(chunk);
+        const details = [];
+        if (/git diff --stat/i.test(stripped))
+            details.push('Checked git diff stats');
+        if (/\bls -la\b/i.test(stripped))
+            details.push('Listed files for verification');
+        if (/status update\?/i.test(stripped))
+            details.push('Asked the worker for a status update');
+        if (/STEP_COMPLETE:/i.test(stripped))
+            details.push('Declared the step complete');
+        for (const detail of details) {
+            await this.trajectory?.ownerMonitoringEvent(step.name, ownerDef.name, detail, {
+                output: stripped.slice(0, 240),
+            });
+        }
+    }
+    resolveAutoStepOwner(specialistDef, agentMap) {
+        if (specialistDef.interactive === false)
+            return specialistDef;
+        const allDefs = [...agentMap.values()].map((d) => WorkflowRunner.resolveAgentDef(d));
+        const candidates = allDefs.filter((d) => d.interactive !== false);
+        const matchesHubRole = (text) => [...WorkflowRunner.HUB_ROLES].some((r) => new RegExp(`\\b${r}\\b`, 'i').test(text));
+        const ownerish = (def) => {
+            const nameLC = def.name.toLowerCase();
+            const roleLC = def.role?.toLowerCase() ?? '';
+            return matchesHubRole(nameLC) || matchesHubRole(roleLC);
+        };
+        const ownerPriority = (def) => {
+            const roleLC = def.role?.toLowerCase() ?? '';
+            const nameLC = def.name.toLowerCase();
+            if (/\blead\b/.test(roleLC) || /\blead\b/.test(nameLC))
+                return 6;
+            if (/\bcoordinator\b/.test(roleLC) || /\bcoordinator\b/.test(nameLC))
+                return 5;
+            if (/\bsupervisor\b/.test(roleLC) || /\bsupervisor\b/.test(nameLC))
+                return 4;
+            if (/\borchestrator\b/.test(roleLC) || /\borchestrator\b/.test(nameLC))
+                return 3;
+            if (/\bhub\b/.test(roleLC) || /\bhub\b/.test(nameLC))
+                return 2;
+            return ownerish(def) ? 1 : 0;
+        };
+        const dedicatedOwner = candidates
+            .filter((d) => d.name !== specialistDef.name && ownerish(d))
+            .sort((a, b) => ownerPriority(b) - ownerPriority(a) || a.name.localeCompare(b.name))[0];
+        if (dedicatedOwner)
+            return dedicatedOwner;
+        return specialistDef;
+    }
+    resolveAutoReviewAgent(ownerDef, agentMap) {
+        const allDefs = [...agentMap.values()].map((d) => WorkflowRunner.resolveAgentDef(d));
+        const isReviewer = (def) => {
+            const roleLC = def.role?.toLowerCase() ?? '';
+            const nameLC = def.name.toLowerCase();
+            return (def.preset === 'reviewer' ||
+                roleLC.includes('review') ||
+                roleLC.includes('critic') ||
+                roleLC.includes('verifier') ||
+                roleLC.includes('qa') ||
+                nameLC.includes('review'));
+        };
+        const reviewerPriority = (def) => {
+            if (def.preset === 'reviewer')
+                return 5;
+            const roleLC = def.role?.toLowerCase() ?? '';
+            const nameLC = def.name.toLowerCase();
+            if (roleLC.includes('review') || nameLC.includes('review'))
+                return 4;
+            if (roleLC.includes('verifier') || roleLC.includes('qa'))
+                return 3;
+            if (roleLC.includes('critic'))
+                return 2;
+            return isReviewer(def) ? 1 : 0;
+        };
+        const dedicated = allDefs
+            .filter((d) => d.name !== ownerDef.name && isReviewer(d))
+            .sort((a, b) => reviewerPriority(b) - reviewerPriority(a) || a.name.localeCompare(b.name))[0];
+        if (dedicated)
+            return dedicated;
+        const alternate = allDefs.find((d) => d.name !== ownerDef.name && d.interactive !== false);
+        if (alternate)
+            return alternate;
+        // Self-review fallback — log a warning since owner reviewing itself is weak.
+        return ownerDef;
+    }
+    assertOwnerCompletionMarker(step, output, injectedTaskText) {
+        const marker = `STEP_COMPLETE:${step.name}`;
+        const taskHasMarker = injectedTaskText.includes(marker);
+        const first = output.indexOf(marker);
+        if (first === -1) {
+            throw new Error(`Step "${step.name}" owner completion marker missing: "${marker}"`);
+        }
+        // PTY output includes injected task text, so require a second marker occurrence
+        // when the marker was present in the injected prompt (either owner contract or supervisor prompt).
+        const outputLikelyContainsInjectedPrompt = output.includes('STEP OWNER CONTRACT') || output.includes('Output exactly: STEP_COMPLETE:');
+        if (taskHasMarker && outputLikelyContainsInjectedPrompt) {
+            const hasSecond = output.includes(marker, first + marker.length);
+            if (!hasSecond) {
+                throw new Error(`Step "${step.name}" owner completion marker missing in agent response: "${marker}"`);
+            }
+        }
+    }
+    async runStepReviewGate(step, resolvedTask, specialistOutput, ownerOutput, ownerDef, reviewerDef, timeoutMs) {
+        const reviewSnippetMax = 12_000;
+        let specialistSnippet = specialistOutput;
+        if (specialistOutput.length > reviewSnippetMax) {
+            const head = Math.floor(reviewSnippetMax / 2);
+            const tail = reviewSnippetMax - head;
+            const omitted = specialistOutput.length - head - tail;
+            specialistSnippet =
+                `${specialistOutput.slice(0, head)}\n` +
+                    `...[truncated ${omitted} chars for review]...\n` +
+                    `${specialistOutput.slice(specialistOutput.length - tail)}`;
+        }
+        let ownerSnippet = ownerOutput;
+        if (ownerOutput.length > reviewSnippetMax) {
+            const head = Math.floor(reviewSnippetMax / 2);
+            const tail = reviewSnippetMax - head;
+            const omitted = ownerOutput.length - head - tail;
+            ownerSnippet =
+                `${ownerOutput.slice(0, head)}\n` +
+                    `...[truncated ${omitted} chars for review]...\n` +
+                    `${ownerOutput.slice(ownerOutput.length - tail)}`;
+        }
+        const reviewTask = `Review workflow step "${step.name}" for completion and safe handoff.\n` +
+            `Step owner: ${ownerDef.name}\n` +
+            `Original objective:\n${resolvedTask}\n\n` +
+            `Specialist output:\n${specialistSnippet}\n\n` +
+            `Owner verification notes:\n${ownerSnippet}\n\n` +
+            `Return exactly:\n` +
+            `REVIEW_DECISION: APPROVE or REJECT\n` +
+            `REVIEW_REASON: <one sentence>\n` +
+            `Then output /exit.`;
+        const safetyTimeoutMs = timeoutMs ?? 600_000;
+        const reviewStep = {
+            name: `${step.name}-review`,
+            type: 'agent',
+            agent: reviewerDef.name,
+            task: reviewTask,
+        };
+        await this.trajectory?.registerAgent(reviewerDef.name, 'reviewer');
+        this.postToChannel(`**[${step.name}]** Review started (reviewer: ${reviewerDef.name})`);
+        const emitReviewCompleted = async (decision, reason) => {
+            await this.trajectory?.reviewCompleted(step.name, reviewerDef.name, decision, reason);
+            this.emit({
+                type: 'step:review-completed',
+                runId: this.currentRunId ?? '',
+                stepName: step.name,
+                reviewerName: reviewerDef.name,
+                decision,
+            });
+        };
+        if (this.executor) {
+            const reviewOutput = await this.executor.executeAgentStep(reviewStep, reviewerDef, reviewTask, safetyTimeoutMs);
+            const parsed = this.parseReviewDecision(reviewOutput);
+            if (!parsed) {
+                throw new Error(`Step "${step.name}" review response malformed from "${reviewerDef.name}" (missing REVIEW_DECISION)`);
+            }
+            await emitReviewCompleted(parsed.decision, parsed.reason);
+            if (parsed.decision === 'rejected') {
+                throw new Error(`Step "${step.name}" review rejected by "${reviewerDef.name}"`);
+            }
+            this.postToChannel(`**[${step.name}]** Review approved by \`${reviewerDef.name}\``);
+            return reviewOutput;
+        }
+        let reviewerHandle;
+        let reviewerReleased = false;
+        let reviewOutput = '';
+        let completedReview;
+        let reviewCompletionPromise;
+        const reviewCompletionStarted = { value: false };
+        const startReviewCompletion = (parsed) => {
+            if (reviewCompletionStarted.value)
+                return;
+            reviewCompletionStarted.value = true;
+            completedReview = parsed;
+            reviewCompletionPromise = (async () => {
+                await emitReviewCompleted(parsed.decision, parsed.reason);
+                if (reviewerHandle && !reviewerReleased) {
+                    reviewerReleased = true;
+                    await reviewerHandle.release().catch(() => undefined);
+                }
+            })();
+        };
+        try {
+            reviewOutput = await this.spawnAndWait(reviewerDef, reviewStep, safetyTimeoutMs, {
+                onSpawned: ({ agent }) => {
+                    reviewerHandle = agent;
+                },
+                onChunk: ({ chunk }) => {
+                    const nextOutput = reviewOutput + WorkflowRunner.stripAnsi(chunk);
+                    reviewOutput = nextOutput;
+                    const parsed = this.parseReviewDecision(nextOutput);
+                    if (parsed) {
+                        startReviewCompletion(parsed);
+                    }
+                },
+            });
+            await reviewCompletionPromise;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (/\btimed out\b/i.test(message)) {
+                this.log(`[${step.name}] Review safety backstop timeout fired after ${safetyTimeoutMs}ms`);
+                throw new Error(`Step "${step.name}" review safety backstop timed out after ${safetyTimeoutMs}ms`);
+            }
+            throw error;
+        }
+        if (!completedReview) {
+            const parsed = this.parseReviewDecision(reviewOutput);
+            if (!parsed) {
+                throw new Error(`Step "${step.name}" review response malformed from "${reviewerDef.name}" (missing REVIEW_DECISION)`);
+            }
+            completedReview = parsed;
+            await emitReviewCompleted(parsed.decision, parsed.reason);
+        }
+        if (completedReview.decision === 'rejected') {
+            throw new Error(`Step "${step.name}" review rejected by "${reviewerDef.name}"`);
+        }
+        this.postToChannel(`**[${step.name}]** Review approved by \`${reviewerDef.name}\``);
+        return reviewOutput;
+    }
+    parseReviewDecision(reviewOutput) {
+        const decisionPattern = /REVIEW_DECISION:\s*(APPROVE|REJECT)/gi;
+        const decisionMatches = [...reviewOutput.matchAll(decisionPattern)];
+        if (decisionMatches.length === 0) {
+            return null;
+        }
+        const outputLikelyContainsEchoedPrompt = reviewOutput.includes('Return exactly') || reviewOutput.includes('REVIEW_DECISION: APPROVE or REJECT');
+        const decisionMatch = outputLikelyContainsEchoedPrompt && decisionMatches.length > 1
+            ? decisionMatches[decisionMatches.length - 1]
+            : decisionMatches[0];
+        const decision = decisionMatch?.[1]?.toUpperCase();
+        if (decision !== 'APPROVE' && decision !== 'REJECT') {
+            return null;
+        }
+        const reasonPattern = /REVIEW_REASON:\s*(.+)/gi;
+        const reasonMatches = [...reviewOutput.matchAll(reasonPattern)];
+        const reasonMatch = outputLikelyContainsEchoedPrompt && reasonMatches.length > 1
+            ? reasonMatches[reasonMatches.length - 1]
+            : reasonMatches[0];
+        const reason = reasonMatch?.[1]?.trim();
+        return {
+            decision: decision === 'APPROVE' ? 'approved' : 'rejected',
+            reason: reason && reason !== '<one sentence>' ? reason : undefined,
+        };
+    }
+    combineStepAndReviewOutput(stepOutput, reviewOutput) {
+        const primary = stepOutput.trimEnd();
+        const review = reviewOutput.trim();
+        if (!review)
+            return primary;
+        if (!primary)
+            return `REVIEW_OUTPUT\n${review}\n`;
+        return `${primary}\n\n---\nREVIEW_OUTPUT\n${review}\n`;
+    }
     /**
      * Build the CLI command and arguments for a non-interactive agent execution.
      * Each CLI has a specific flag for one-shot prompt mode.
@@ -2096,7 +2601,7 @@ export class WorkflowRunner {
             this.unregisterWorker(agentName);
         }
     }
-    async spawnAndWait(agentDef, step, timeoutMs) {
+    async spawnAndWait(agentDef, step, timeoutMs, options = {}) {
         // Branch: non-interactive agents run as simple subprocesses
         if (agentDef.interactive === false) {
             return this.execNonInteractive(agentDef, step, timeoutMs);
@@ -2104,13 +2609,15 @@ export class WorkflowRunner {
         if (!this.relay) {
             throw new Error('AgentRelay not initialized');
         }
-        // Deterministic name: step name + first 8 chars of run ID.
-        let agentName = `${step.name}-${(this.currentRunId ?? this.generateShortId()).slice(0, 8)}`;
+        // Deterministic name: step name + optional role suffix + first 8 chars of run ID.
+        const requestedName = `${step.name}${options.agentNameSuffix ? `-${options.agentNameSuffix}` : ''}-${(this.currentRunId ?? this.generateShortId()).slice(0, 8)}`;
+        let agentName = requestedName;
         // Only inject delegation guidance for lead/coordinator agents, not spokes/workers.
         // In non-hub patterns (pipeline, dag, etc.) every agent is autonomous so they all get it.
         const role = agentDef.role?.toLowerCase() ?? '';
         const nameLC = agentDef.name.toLowerCase();
-        const isHub = WorkflowRunner.HUB_ROLES.has(nameLC) || [...WorkflowRunner.HUB_ROLES].some((r) => role.includes(r));
+        const isHub = WorkflowRunner.HUB_ROLES.has(nameLC) ||
+            [...WorkflowRunner.HUB_ROLES].some((r) => new RegExp(`\\b${r}\\b`).test(role));
         const pattern = this.currentConfig?.swarm.pattern;
         const isHubPattern = pattern && WorkflowRunner.HUB_PATTERNS.has(pattern);
         const delegationGuidance = isHub || !isHubPattern ? this.buildDelegationGuidance(agentDef.cli, timeoutMs) : '';
@@ -2139,6 +2646,7 @@ export class WorkflowRunner {
             // Write raw output (with ANSI codes) to log file so dashboard's
             // XTermLogViewer can render colors/formatting natively via xterm.js
             logStream.write(chunk);
+            options.onChunk?.({ agentName, chunk });
         });
         const agentChannels = this.channel ? [this.channel] : agentDef.channels;
         let agent;
@@ -2187,10 +2695,12 @@ export class WorkflowRunner {
                         const stripped = WorkflowRunner.stripAnsi(chunk);
                         this.ptyOutputBuffers.get(agent.name)?.push(stripped);
                         newLogStream.write(chunk);
+                        options.onChunk?.({ agentName: agent.name, chunk });
                     });
                 }
                 agentName = agent.name;
             }
+            await options.onSpawned?.({ requestedName, actualName: agent.name, agent });
             // Register in workers.json so `agents:kill` can find this agent
             let workerPid;
             try {
@@ -2260,6 +2770,7 @@ export class WorkflowRunner {
                 this.ptyLogStreams.delete(agentName);
             }
             this.unregisterWorker(agentName);
+            this.supervisedRuntimeAgents.delete(agentName);
         }
         let output;
         if (ptyChunks.length > 0) {
@@ -2417,7 +2928,7 @@ export class WorkflowRunner {
             const role = agentDef.role?.toLowerCase() ?? '';
             const nameLC = agentDef.name.toLowerCase();
             if (WorkflowRunner.HUB_ROLES.has(nameLC) ||
-                [...WorkflowRunner.HUB_ROLES].some((r) => role.includes(r))) {
+                [...WorkflowRunner.HUB_ROLES].some((r) => new RegExp(`\\b${r}\\b`).test(role))) {
                 // Found a hub candidate — check if we have a live handle
                 const handle = this.activeAgentHandles.get(agentDef.name);
                 if (handle)