agent-relay 3.1.15 → 3.1.17

package/dist/index.cjs

@@ -9052,6 +9052,9 @@ var AgentRelayClient = class _AgentRelayClient {
       this.stderrListeners.delete(listener);
     };
   }
+  get brokerPid() {
+    return this.child?.pid;
+  }
   async start() {
     if (this.child) {
       return;
@@ -47269,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;
+    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 === agent)) {
+    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. */
@@ -47610,6 +47661,10 @@ 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 = {}) {
     this.db = options.db ?? new InMemoryWorkflowDb();
     this.workspaceId = options.workspaceId ?? "local";
@@ -47619,6 +47674,75 @@ var WorkflowRunner = class _WorkflowRunner {
     this.workersPath = import_node_path8.default.join(this.cwd, ".agent-relay", "team", "workers.json");
     this.executor = options.executor;
   }
+  // ── Path resolution ─────────────────────────────────────────────────────
+  /** Expand environment variables like $HOME or $VAR in a path string. */
+  static resolveEnvVars(p) {
+    return p.replace(/\$([A-Za-z_][A-Za-z0-9_]*)/g, (_match, varName) => {
+      return process.env[varName] ?? _match;
+    });
+  }
+  /**
+   * Resolve and validate the top-level `paths` definitions from the config.
+   * Returns a map of name → absolute directory path.
+   * Throws if a required path does not exist.
+   */
+  resolvePathDefinitions(pathDefs, baseCwd) {
+    const resolved = /* @__PURE__ */ new Map();
+    const errors = [];
+    const warnings = [];
+    if (!pathDefs || pathDefs.length === 0)
+      return { resolved, errors, warnings };
+    const seenNames = /* @__PURE__ */ new Set();
+    for (const pd of pathDefs) {
+      if (seenNames.has(pd.name)) {
+        errors.push(`Duplicate path name "${pd.name}"`);
+        continue;
+      }
+      seenNames.add(pd.name);
+      const expanded = _WorkflowRunner.resolveEnvVars(pd.path);
+      const abs = import_node_path8.default.resolve(baseCwd, expanded);
+      resolved.set(pd.name, abs);
+      const isRequired = pd.required !== false;
+      if (!(0, import_node_fs4.existsSync)(abs)) {
+        if (isRequired) {
+          errors.push(`Path "${pd.name}" resolves to "${abs}" which does not exist (required)`);
+        } else {
+          warnings.push(`Path "${pd.name}" resolves to "${abs}" which does not exist (optional)`);
+        }
+      }
+    }
+    return { resolved, errors, warnings };
+  }
+  /**
+   * Resolve an agent's effective working directory, considering `workdir` (named path reference)
+   * and `cwd` (explicit path). `workdir` takes precedence when both are set.
+   */
+  resolveAgentCwd(agent) {
+    if (agent.workdir) {
+      const resolved = this.resolvedPaths.get(agent.workdir);
+      if (!resolved) {
+        throw new Error(`Agent "${agent.name}" references workdir "${agent.workdir}" which is not defined in paths`);
+      }
+      return resolved;
+    }
+    if (agent.cwd) {
+      return import_node_path8.default.resolve(this.cwd, agent.cwd);
+    }
+    return this.cwd;
+  }
+  /**
+   * Resolve a step's working directory from its `workdir` field (named path reference).
+   * Returns undefined if no workdir is set.
+   */
+  resolveStepWorkdir(step) {
+    if (!step.workdir)
+      return void 0;
+    const resolved = this.resolvedPaths.get(step.workdir);
+    if (!resolved) {
+      throw new Error(`Step "${step.name}" references workdir "${step.workdir}" which is not defined in paths`);
+    }
+    return resolved;
+  }
   // ── Progress logging ────────────────────────────────────────────────────
   /** Log a progress message with elapsed time since run start. */
   log(msg) {
@@ -47852,6 +47976,15 @@ var WorkflowRunner = class _WorkflowRunner {
         estimatedWaves: 0
       };
     }
+    const pathResult = this.resolvePathDefinitions(resolved.paths, this.cwd);
+    errors.push(...pathResult.errors);
+    warnings.push(...pathResult.warnings);
+    const dryRunPaths = pathResult.resolved;
+    for (const agent of resolved.agents) {
+      if (agent.workdir && !dryRunPaths.has(agent.workdir)) {
+        errors.push(`Agent "${agent.name}" references workdir "${agent.workdir}" which is not defined in paths`);
+      }
+    }
     const workflows = resolved.workflows ?? [];
     const workflow2 = workflowName ? workflows.find((w) => w.name === workflowName) : workflows[0];
     if (!workflow2) {
@@ -47909,6 +48042,11 @@ ${err.suggestion}`);
         stepAgentCounts.set(step.agent, (stepAgentCounts.get(step.agent) ?? 0) + 1);
       }
     }
+    for (const step of resolvedSteps) {
+      if (step.workdir && !dryRunPaths.has(step.workdir)) {
+        errors.push(`Step "${step.name}" references workdir "${step.workdir}" which is not defined in paths`);
+      }
+    }
     for (const agent of resolved.agents) {
       if (agent.cwd) {
         const resolvedCwd = import_node_path8.default.resolve(this.cwd, agent.cwd);
@@ -47989,7 +48127,7 @@ ${err.suggestion}`);
       name: a.name,
       cli: a.cli,
       role: a.role,
-      cwd: a.cwd,
+      cwd: a.workdir ? dryRunPaths.get(a.workdir) : a.cwd,
       stepCount: stepAgentCounts.get(a.name) ?? 0
     }));
     const waves = [];
@@ -48235,6 +48373,17 @@ ${err.suggestion}`);
   /** Execute a named workflow from a validated config. */
   async execute(config3, workflowName, vars) {
     const resolved = vars ? this.resolveVariables(config3, vars) : config3;
+    const pathResult = this.resolvePathDefinitions(resolved.paths, this.cwd);
+    if (pathResult.errors.length > 0) {
+      throw new Error(`Path validation failed:
+  ${pathResult.errors.join("\n  ")}`);
+    }
+    this.resolvedPaths = pathResult.resolved;
+    if (this.resolvedPaths.size > 0) {
+      for (const [name, abs] of this.resolvedPaths) {
+        console.log(`[workflow] path "${name}" \u2192 ${abs}`);
+      }
+    }
     const workflows = resolved.workflows ?? [];
     const workflow2 = workflowName ? workflows.find((w) => w.name === workflowName) : workflows[0];
     if (!workflow2) {
@@ -48294,6 +48443,12 @@ ${err.suggestion}`);
       throw new Error(`Run "${runId}" is in status "${run.status}" and cannot be resumed`);
     }
     const config3 = vars ? this.resolveVariables(run.config, vars) : run.config;
+    const pathResult = this.resolvePathDefinitions(config3.paths, this.cwd);
+    if (pathResult.errors.length > 0) {
+      throw new Error(`Path validation failed:
+  ${pathResult.errors.join("\n  ")}`);
+    }
+    this.resolvedPaths = pathResult.resolved;
     const workflows = config3.workflows ?? [];
     const workflow2 = workflows.find((w) => w.name === run.workflowName);
     if (!workflow2) {
@@ -48418,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)) {
@@ -48520,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;
@@ -48769,9 +48929,10 @@ ${trimmedOutput.slice(0, 200)}`);
       const value = this.resolveDotPath(key, stepOutputContext);
       return value !== void 0 ? String(value) : _match;
     });
+    const stepCwd = this.resolveStepWorkdir(step) ?? this.cwd;
     try {
       if (this.executor?.executeDeterministicStep) {
-        const result = await this.executor.executeDeterministicStep(step, resolvedCommand, this.cwd);
+        const result = await this.executor.executeDeterministicStep(step, resolvedCommand, stepCwd);
         const failOnError = step.failOnError !== false;
         if (failOnError && result.exitCode !== 0) {
           throw new Error(`Command failed with exit code ${result.exitCode}: ${result.output.slice(0, 500)}`);
@@ -48793,7 +48954,7 @@ ${trimmedOutput.slice(0, 200)}`);
       const output = await new Promise((resolve3, reject) => {
         const child = (0, import_node_child_process3.spawn)("sh", ["-c", resolvedCommand], {
           stdio: "pipe",
-          cwd: this.cwd,
+          cwd: stepCwd,
           env: { ...process.env }
         });
         const stdoutChunks = [];
@@ -48896,19 +49057,20 @@ ${trimmedOutput.slice(0, 200)}`);
     const baseBranch = step.baseBranch ? this.interpolateStepTask(step.baseBranch, stepOutputContext) : "HEAD";
     const worktreePath = step.path ? this.interpolateStepTask(step.path, stepOutputContext) : import_node_path8.default.join(".worktrees", step.name);
     const createBranch = step.createBranch !== false;
+    const stepCwd = this.resolveStepWorkdir(step) ?? this.cwd;
     if (!branch) {
       const errorMsg = 'Worktree step missing required "branch" field';
       await this.markStepFailed(state, errorMsg, runId);
       throw new Error(`Step "${step.name}" failed: ${errorMsg}`);
     }
     try {
-      const absoluteWorktreePath = import_node_path8.default.resolve(this.cwd, worktreePath);
+      const absoluteWorktreePath = import_node_path8.default.resolve(stepCwd, worktreePath);
       const checkBranchCmd = `git rev-parse --verify --quiet ${branch} 2>/dev/null`;
       let branchExists = false;
       await new Promise((resolve3) => {
         const checkChild = (0, import_node_child_process3.spawn)("sh", ["-c", checkBranchCmd], {
           stdio: "pipe",
-          cwd: this.cwd,
+          cwd: stepCwd,
           env: { ...process.env }
         });
         checkChild.on("close", (code) => {
@@ -48930,7 +49092,7 @@ ${trimmedOutput.slice(0, 200)}`);
       const output = await new Promise((resolve3, reject) => {
         const child = (0, import_node_child_process3.spawn)("sh", ["-c", worktreeCmd], {
           stdio: "pipe",
-          cwd: this.cwd,
+          cwd: stepCwd,
           env: { ...process.env }
         });
         const stdoutChunks = [];
@@ -49024,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();
@@ -49051,41 +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;
           }
         }
-        this.log(`[${step.name}] Spawning agent "${agentDef.name}" (cli: ${agentDef.cli})`);
-        const resolvedStep = { ...step, task: resolvedTask };
-        const output = this.executor ? await this.executor.executeAgentStep(resolvedStep, agentDef, resolvedTask, timeoutMs) : await this.spawnAndWait(agentDef, resolvedStep, timeoutMs);
-        this.log(`[${step.name}] Agent "${agentDef.name}" exited`);
+        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;
+        }
         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,
@@ -49096,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.
@@ -49206,7 +49848,7 @@ DO NOT:
       const output = await new Promise((resolve3, reject) => {
         const child = (0, import_node_child_process3.spawn)(cmd, args, {
           stdio: ["ignore", "pipe", "pipe"],
-          cwd: agentDef.cwd ? import_node_path8.default.resolve(this.cwd, agentDef.cwd) : this.cwd,
+          cwd: this.resolveAgentCwd(agentDef),
           env: this.getRelayEnv() ?? { ...process.env }
         });
         this.registerWorker(agentName, agentDef.cli, step.task ?? "", child.pid, false);
@@ -49289,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) : "";
@@ -49313,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;
@@ -49320,6 +49964,7 @@ DO NOT:
     let stopHeartbeat;
     let ptyChunks = [];
     try {
+      const agentCwd = this.resolveAgentCwd(agentDef);
       agent = await this.relay.spawnPty({
         name: agentName,
         cli: agentDef.cli,
@@ -49328,7 +49973,7 @@ DO NOT:
         channels: agentChannels,
         task: taskWithExit,
         idleThresholdSecs: agentDef.constraints?.idleThresholdSecs,
-        cwd: agentDef.cwd ? import_node_path8.default.resolve(this.cwd, agentDef.cwd) : void 0
+        cwd: agentCwd !== this.cwd ? agentCwd : void 0
       });
       if (agent.name !== agentName) {
         const oldName = agentName;
@@ -49354,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();
@@ -49410,6 +50057,7 @@ DO NOT:
         this.ptyLogStreams.delete(agentName);
       }
       this.unregisterWorker(agentName);
+      this.supervisedRuntimeAgents.delete(agentName);
     }
     let output;
     if (ptyChunks.length > 0) {
@@ -49535,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;