agent-relay 3.1.16 → 3.1.17

package/dist/index.cjs

@@ -47272,18 +47272,66 @@ var WorkflowTrajectory = class {
   }
   // ── Step events ────────────────────────────────────────────────────────────
   /** Record step started — captures intent, not just assignment. */
-  async stepStarted(step, agent) {
+  async stepStarted(step, agent, participants) {
     if (!this.enabled || !this.trajectory)
       return;
-    if (!this.trajectory.agents.some((a) => a.name === agent)) {
+    await this.registerAgent(agent, participants?.role ?? step.agent ?? "deterministic");
+    if (participants?.owner && participants.owner !== agent) {
+      await this.registerAgent(participants.owner, "owner");
+    }
+    if (participants?.specialist) {
+      await this.registerAgent(participants.specialist, "specialist");
+    }
+    if (participants?.reviewer) {
+      await this.registerAgent(participants.reviewer, "reviewer");
+    }
+    const intent = step.task ? step.task.trim().split(/\n|\.(?=\s)/)[0].trim().slice(0, 120) : `${step.type ?? "deterministic"} step`;
+    this.addEvent("note", `"${step.name}": ${intent}`, void 0, { agent });
+    await this.flush();
+  }
+  async registerAgent(name, role) {
+    if (!this.enabled || !this.trajectory)
+      return;
+    if (!this.trajectory.agents.some((a) => a.name === name)) {
       this.trajectory.agents.push({
-        name: agent,
-        role: step.agent ?? "deterministic",
+        name,
+        role,
         joinedAt: (/* @__PURE__ */ new Date()).toISOString()
       });
+      await this.flush();
     }
-    const intent = step.task ? step.task.trim().split(/\n|\.(?=\s)/)[0].trim().slice(0, 120) : `${step.type ?? "deterministic"} step`;
-    this.addEvent("note", `"${step.name}": ${intent}`, void 0, { agent });
+  }
+  async stepSupervisionAssigned(step, supervised) {
+    if (!this.enabled || !this.trajectory)
+      return;
+    await this.registerAgent(supervised.owner.name, "owner");
+    await this.registerAgent(supervised.specialist.name, "specialist");
+    if (supervised.reviewer?.name) {
+      await this.registerAgent(supervised.reviewer.name, "reviewer");
+    }
+    const reviewerNote = supervised.reviewer?.name ? `, reviewer=${supervised.reviewer.name}` : "";
+    this.addEvent("decision", `"${step.name}" supervision assigned \u2192 owner=${supervised.owner.name}, specialist=${supervised.specialist.name}${reviewerNote}`, "medium", {
+      owner: supervised.owner.name,
+      specialist: supervised.specialist.name,
+      reviewer: supervised.reviewer?.name
+    });
+    await this.flush();
+  }
+  async ownerMonitoringEvent(stepName, owner, detail, raw) {
+    if (!this.enabled || !this.trajectory)
+      return;
+    this.addEvent("note", `"${stepName}" owner ${owner}: ${detail}`, "medium", raw ? { owner, ...raw } : { owner });
+    await this.flush();
+  }
+  async reviewCompleted(stepName, reviewerName, decision, reason) {
+    if (!this.enabled || !this.trajectory)
+      return;
+    this.addEvent("review-completed", `"${stepName}" review ${decision} by ${reviewerName}`, "medium", {
+      stepName,
+      reviewer: reviewerName,
+      decision,
+      reason
+    });
     await this.flush();
   }
   /** Record step completed — captures what was accomplished. */
@@ -47613,6 +47661,8 @@ var WorkflowRunner = class _WorkflowRunner {
   lastIdleLog = /* @__PURE__ */ new Map();
   /** Tracks last logged activity type per agent to avoid duplicate status lines. */
   lastActivity = /* @__PURE__ */ new Map();
+  /** Runtime-name lookup for agents participating in supervised owner flows. */
+  supervisedRuntimeAgents = /* @__PURE__ */ new Map();
   /** Resolved named paths from the top-level `paths` config, keyed by name → absolute directory. */
   resolvedPaths = /* @__PURE__ */ new Map();
   constructor(options = {}) {
@@ -48523,6 +48573,10 @@ ${err.suggestion}`);
           const fromShort = msg.from.replace(/-[a-f0-9]{6,}$/, "");
           const toShort = msg.to.replace(/-[a-f0-9]{6,}$/, "");
           this.log(`[msg] ${fromShort} \u2192 ${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) => {
           if (!this.activeAgentHandles.has(agent.name)) {
@@ -48625,6 +48679,7 @@ ${err.suggestion}`);
       }
       this.lastIdleLog.clear();
       this.lastActivity.clear();
+      this.supervisedRuntimeAgents.clear();
       this.log("Shutting down broker...");
       await this.relay?.shutdown();
       this.relay = void 0;
@@ -49131,10 +49186,19 @@ ${trimmedOutput.slice(0, 200)}`);
     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) : void 0;
+    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 ?? 1e3;
-    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();
@@ -49158,48 +49222,95 @@ ${trimmedOutput.slice(0, 200)}`);
           updatedAt: (/* @__PURE__ */ 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
+        });
         const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
         let resolvedTask = this.interpolateStepTask(step.task ?? "", stepOutputContext);
-        if (agentDef.interactive !== false) {
+        if (specialistDef.interactive !== false || ownerDef.interactive !== false) {
           const nonInteractiveInfo = this.buildNonInteractiveAwareness(agentMap, stepStates);
           if (nonInteractiveInfo) {
             resolvedTask += nonInteractiveInfo;
           }
         }
-        let effectiveAgentDef = agentDef;
-        if (step.workdir) {
-          const stepWorkdir = this.resolveStepWorkdir(step);
-          if (stepWorkdir) {
-            effectiveAgentDef = { ...agentDef, cwd: stepWorkdir, workdir: void 0 };
+        const applyStepWorkdir = (def) => {
+          if (step.workdir) {
+            const stepWorkdir = this.resolveStepWorkdir(step);
+            if (stepWorkdir) {
+              return { ...def, cwd: stepWorkdir, workdir: void 0 };
+            }
+          }
+          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;
         }
-        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`);
         if (step.verification) {
-          this.runVerification(step.verification, output, step.name, resolvedTask);
+          this.runVerification(step.verification, specialistOutput, step.name, resolvedTask);
+        }
+        let combinedOutput = specialistOutput;
+        if (usesOwnerFlow && reviewDef) {
+          const remainingMs = timeoutMs ? Math.max(0, timeoutMs - ownerElapsed) : void 0;
+          const reviewOutput = await this.runStepReviewGate(step, resolvedTask, specialistOutput, ownerOutput, ownerDef, reviewDef, remainingMs);
+          combinedOutput = this.combineStepAndReviewOutput(specialistOutput, reviewOutput);
         }
         state.row.status = "completed";
-        state.row.output = output;
+        state.row.output = combinedOutput;
         state.row.completedAt = (/* @__PURE__ */ new Date()).toISOString();
         await this.db.updateStep(state.row.id, {
           status: "completed",
-          output,
+          output: combinedOutput,
           completedAt: state.row.completedAt,
           updatedAt: (/* @__PURE__ */ new Date()).toISOString()
         });
-        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 });
+        }
       }
     }
-    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) : void 0;
     await this.trajectory?.stepFailed(step, lastError ?? "Unknown error", maxRetries + 1, maxRetries, {
       agent: agentName,
@@ -49210,6 +49321,423 @@ ${trimmedOutput.slice(0, 200)}`);
     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 + `
+
+---
+STEP OWNER CONTRACT:
+- You are the accountable owner for step "${step.name}".
+` + (specialistNote ? `- ${specialistNote}
+` : "") + `- If you delegate, you must still verify completion yourself.
+- Before exiting, provide an explicit completion line: STEP_COMPLETE:${step.name}
+- 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}".
+
+Worker: ${supervised.specialist.name} (runtime: ${workerRuntimeName}) on ${channelLine}
+Task: ${originalTask}
+
+Your job: Monitor the worker and determine when the task is complete.
+
+How to verify completion:
+- Watch ${channelLine} for the worker's progress messages and mirrored PTY output
+- Check file changes: run \`git diff --stat\` or inspect expected files directly
+- Ask the worker directly on ${channelLine} if you need a status update
+` + verificationGuide + `
+When you're satisfied the work is done correctly:
+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)}
+`;
+      case "file_exists":
+        return `- Verification gate: confirm the file exists at ${JSON.stringify(verification.value)}
+`;
+      case "exit_code":
+        return `- Verification gate: confirm the worker exits with code ${JSON.stringify(verification.value)}
+`;
+      case "custom":
+        return `- Verification gate: apply the custom verification rule ${JSON.stringify(verification.value)}
+`;
+      default:
+        return "";
+    }
+  }
+  async executeSupervisedAgentStep(step, supervised, resolvedTask, timeoutMs) {
+    if (this.executor) {
+      const supervisorTask2 = this.buildOwnerSupervisorTask(step, resolvedTask, supervised, supervised.specialist.name);
+      const specialistStep2 = { ...step, task: resolvedTask };
+      const ownerStep2 = {
+        ...step,
+        name: `${step.name}-owner`,
+        agent: supervised.owner.name,
+        task: supervisorTask2
+      };
+      this.log(`[${step.name}] Spawning specialist "${supervised.specialist.name}" and owner "${supervised.owner.name}"`);
+      const specialistPromise = this.executor.executeAgentStep(specialistStep2, supervised.specialist, resolvedTask, timeoutMs);
+      const ownerStartTime2 = Date.now();
+      const ownerOutput = await this.executor.executeAgentStep(ownerStep2, supervised.owner, supervisorTask2, timeoutMs);
+      const ownerElapsed = Date.now() - ownerStartTime2;
+      this.assertOwnerCompletionMarker(step, ownerOutput, supervisorTask2);
+      const specialistOutput = await specialistPromise;
+      return { specialistOutput, ownerOutput, ownerElapsed };
+    }
+    let workerHandle;
+    let workerRuntimeName = supervised.specialist.name;
+    let workerSpawned = false;
+    let workerReleased = false;
+    let resolveWorkerSpawn;
+    let rejectWorkerSpawn;
+    const workerReady = new Promise((resolve3, reject) => {
+      resolveWorkerSpawn = resolve3;
+      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((error95) => {
+      if (!workerSpawned) {
+        workerSpawned = true;
+        rejectWorkerSpawn(error95);
+      }
+      throw error95;
+    });
+    const workerSettled = workerPromise.catch(() => void 0);
+    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((error95) => {
+      const message = error95 instanceof Error ? error95.message : String(error95);
+      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 (error95) {
+      const message = error95 instanceof Error ? error95.message : String(error95);
+      if (!workerReleased && workerHandle) {
+        await workerHandle.release().catch(() => void 0);
+      }
+      await workerSettled;
+      if (/\btimed out\b/i.test(message)) {
+        throw new Error(`Step "${step.name}" owner timed out after ${timeoutMs ?? "unknown"}ms`);
+      }
+      throw error95;
+    }
+  }
+  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;
+    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}"`);
+    }
+    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 = 12e3;
+    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)}
+...[truncated ${omitted} chars for review]...
+${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)}
+...[truncated ${omitted} chars for review]...
+${ownerOutput.slice(ownerOutput.length - tail)}`;
+    }
+    const reviewTask = `Review workflow step "${step.name}" for completion and safe handoff.
+Step owner: ${ownerDef.name}
+Original objective:
+${resolvedTask}
+
+Specialist output:
+${specialistSnippet}
+
+Owner verification notes:
+${ownerSnippet}
+
+Return exactly:
+REVIEW_DECISION: APPROVE or REJECT
+REVIEW_REASON: <one sentence>
+Then output /exit.`;
+    const safetyTimeoutMs = timeoutMs ?? 6e5;
+    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 reviewOutput2 = await this.executor.executeAgentStep(reviewStep, reviewerDef, reviewTask, safetyTimeoutMs);
+      const parsed = this.parseReviewDecision(reviewOutput2);
+      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 reviewOutput2;
+    }
+    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(() => void 0);
+        }
+      })();
+    };
+    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 (error95) {
+      const message = error95 instanceof Error ? error95.message : String(error95);
+      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 error95;
+    }
+    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 : void 0
+    };
+  }
+  combineStepAndReviewOutput(stepOutput, reviewOutput) {
+    const primary = stepOutput.trimEnd();
+    const review = reviewOutput.trim();
+    if (!review)
+      return primary;
+    if (!primary)
+      return `REVIEW_OUTPUT
+${review}
+`;
+    return `${primary}
+
+---
+REVIEW_OUTPUT
+${review}
+`;
+  }
   /**
    * Build the CLI command and arguments for a non-interactive agent execution.
    * Each CLI has a specific flag for one-shot prompt mode.
@@ -49403,17 +49931,18 @@ DO NOT:
       this.unregisterWorker(agentName);
     }
   }
-  async spawnAndWait(agentDef, step, timeoutMs) {
+  async spawnAndWait(agentDef, step, timeoutMs, options = {}) {
     if (agentDef.interactive === false) {
       return this.execNonInteractive(agentDef, step, timeoutMs);
     }
     if (!this.relay) {
       throw new Error("AgentRelay not initialized");
     }
-    let agentName = `${step.name}-${(this.currentRunId ?? this.generateShortId()).slice(0, 8)}`;
+    const requestedName = `${step.name}${options.agentNameSuffix ? `-${options.agentNameSuffix}` : ""}-${(this.currentRunId ?? this.generateShortId()).slice(0, 8)}`;
+    let agentName = requestedName;
     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) : "";
@@ -49427,6 +49956,7 @@ DO NOT:
       const stripped = _WorkflowRunner.stripAnsi(chunk);
       this.ptyOutputBuffers.get(agentName)?.push(stripped);
       logStream.write(chunk);
+      options.onChunk?.({ agentName, chunk });
     });
     const agentChannels = this.channel ? [this.channel] : agentDef.channels;
     let agent;
@@ -49469,10 +49999,12 @@ DO NOT:
             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 });
       let workerPid;
       try {
         const rawAgents = await this.relay.listAgentsRaw();
@@ -49525,6 +50057,7 @@ DO NOT:
         this.ptyLogStreams.delete(agentName);
       }
       this.unregisterWorker(agentName);
+      this.supervisedRuntimeAgents.delete(agentName);
     }
     let output;
     if (ptyChunks.length > 0) {
@@ -49650,7 +50183,7 @@ DO NOT:
         continue;
       const role = agentDef.role?.toLowerCase() ?? "";
       const nameLC = agentDef.name.toLowerCase();
-      if (_WorkflowRunner.HUB_ROLES.has(nameLC) || [..._WorkflowRunner.HUB_ROLES].some((r) => role.includes(r))) {
+      if (_WorkflowRunner.HUB_ROLES.has(nameLC) || [..._WorkflowRunner.HUB_ROLES].some((r) => new RegExp(`\\b${r}\\b`).test(role))) {
         const handle = this.activeAgentHandles.get(agentDef.name);
         if (handle)
           return handle;