agent-relay 3.1.19 → 3.1.21

package/dist/index.cjs

@@ -9102,7 +9102,8 @@ var AgentRelayClient = class _AgentRelayClient {
       agent,
       ...input.task != null ? { initial_task: input.task } : {},
       ...input.idleThresholdSecs != null ? { idle_threshold_secs: input.idleThresholdSecs } : {},
-      ...input.continueFrom != null ? { continue_from: input.continueFrom } : {}
+      ...input.continueFrom != null ? { continue_from: input.continueFrom } : {},
+      ...input.skipRelayPrompt != null ? { skip_relay_prompt: input.skipRelayPrompt } : {}
     });
     return result;
   }
@@ -9117,7 +9118,8 @@ var AgentRelayClient = class _AgentRelayClient {
     };
     const result = await this.requestOk("spawn_agent", {
       agent,
-      ...input.task != null ? { initial_task: input.task } : {}
+      ...input.task != null ? { initial_task: input.task } : {},
+      ...input.skipRelayPrompt != null ? { skip_relay_prompt: input.skipRelayPrompt } : {}
     });
     return result;
   }
@@ -9132,7 +9134,8 @@ var AgentRelayClient = class _AgentRelayClient {
         provider: input.provider,
         args: input.args,
         channels: input.channels,
-        task: input.task
+        task: input.task,
+        skipRelayPrompt: input.skipRelayPrompt
       });
     }
     return this.spawnPty({
@@ -9148,7 +9151,8 @@ var AgentRelayClient = class _AgentRelayClient {
       shadowMode: input.shadowMode,
       idleThresholdSecs: input.idleThresholdSecs,
       restartPolicy: input.restartPolicy,
-      continueFrom: input.continueFrom
+      continueFrom: input.continueFrom,
+      skipRelayPrompt: input.skipRelayPrompt
     });
   }
   async spawnClaude(input) {
@@ -9214,25 +9218,35 @@ var AgentRelayClient = class _AgentRelayClient {
     if (!this.child) {
       return;
     }
-    try {
-      await this.requestOk("shutdown", {});
-    } catch {
-    }
+    void this.requestOk("shutdown", {}).catch(() => {
+    });
     const child = this.child;
     const wait = this.exitPromise ?? Promise.resolve();
-    const timeout = setTimeout(() => {
-      if (!child.killed) {
-        child.kill("SIGTERM");
-      }
-    }, this.options.shutdownTimeoutMs);
-    try {
-      await wait;
-    } finally {
-      clearTimeout(timeout);
-      if (this.child) {
-        this.child.kill("SIGKILL");
-      }
+    const waitForExit = async (timeoutMs) => {
+      let timer;
+      const result = await Promise.race([
+        wait.then(() => true),
+        new Promise((resolve3) => {
+          timer = setTimeout(() => resolve3(false), timeoutMs);
+        })
+      ]);
+      if (timer !== void 0)
+        clearTimeout(timer);
+      return result;
+    };
+    if (await waitForExit(this.options.shutdownTimeoutMs)) {
+      return;
+    }
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill("SIGTERM");
     }
+    if (await waitForExit(1e3)) {
+      return;
+    }
+    if (child.exitCode === null && child.signalCode === null) {
+      child.kill("SIGKILL");
+    }
+    await waitForExit(1e3);
   }
   async waitForExit() {
     if (!this.child) {
@@ -9250,8 +9264,7 @@ var AgentRelayClient = class _AgentRelayClient {
       "init",
       "--name",
       this.options.brokerName,
-      "--channels",
-      this.options.channels.join(","),
+      ...this.options.channels.length > 0 ? ["--channels", this.options.channels.join(",")] : [],
       ...this.options.binaryArgs
     ];
     const env = { ...this.options.env };
@@ -9262,7 +9275,7 @@ var AgentRelayClient = class _AgentRelayClient {
         env.PATH = `${binDir}${import_node_path.default.delimiter}${currentPath}`;
       }
     }
-    console.log(`[broker] Starting: ${resolvedBinary} ${args.join(" ")}`);
+    console.error(`[broker] Starting: ${resolvedBinary} ${args.join(" ")}`);
     const child = (0, import_node_child_process.spawn)(resolvedBinary, args, {
       cwd: this.options.cwd,
       env,
@@ -9298,7 +9311,7 @@ var AgentRelayClient = class _AgentRelayClient {
       });
     });
     const helloAck = await this.requestHello();
-    console.log("[broker] Broker ready (hello handshake complete)");
+    console.error("[broker] Broker ready (hello handshake complete)");
     if (helloAck.workspace_key) {
       this.workspaceKey = helloAck.workspace_key;
     }
@@ -45196,7 +45209,7 @@ var AgentRelay = class {
     this.clientOptions = {
       binaryPath: options.binaryPath,
       binaryArgs: options.binaryArgs,
-      brokerName: options.brokerName,
+      brokerName: options.brokerName ?? options.workspaceName,
       channels: this.defaultChannels,
       cwd: options.cwd,
       env: options.env,
@@ -45255,7 +45268,8 @@ var AgentRelay = class {
         shadowOf: input.shadowOf,
         shadowMode: input.shadowMode,
         idleThresholdSecs: input.idleThresholdSecs,
-        restartPolicy: input.restartPolicy
+        restartPolicy: input.restartPolicy,
+        skipRelayPrompt: input.skipRelayPrompt
       });
     } catch (error95) {
       await this.invokeLifecycleHook(input.onError, {
@@ -45288,6 +45302,7 @@ var AgentRelay = class {
       shadowMode: options?.shadowMode,
       idleThresholdSecs: options?.idleThresholdSecs,
       restartPolicy: options?.restartPolicy,
+      skipRelayPrompt: options?.skipRelayPrompt,
       onStart: options?.onStart,
       onSuccess: options?.onSuccess,
       onError: options?.onError
@@ -45597,10 +45612,21 @@ var AgentRelay = class {
       this.unsubEvent();
       this.unsubEvent = void 0;
     }
-    if (this.client) {
-      await this.client.shutdown();
-      this.client = void 0;
+    let client = this.client;
+    if (!client && this.startPromise) {
+      try {
+        client = await this.startPromise;
+      } catch {
+        client = void 0;
+      }
+    }
+    if (client) {
+      await client.shutdown();
+      if (this.client === client) {
+        this.client = void 0;
+      }
     }
+    this.startPromise = void 0;
     this.knownAgents.clear();
     this.readyAgents.clear();
     this.messageReadyAgents.clear();
@@ -45672,8 +45698,10 @@ var AgentRelay = class {
    *   4. Auto-create a fresh workspace via the Relaycast REST API
    */
   async ensureRelaycastApiKey() {
-    if (this.relayApiKey)
+    if (this.relayApiKey) {
+      this.wireRelaycastBaseUrl();
       return;
+    }
     const envKey = this.clientOptions.env?.RELAY_API_KEY ?? process.env.RELAY_API_KEY;
     if (envKey) {
       this.relayApiKey = envKey;
@@ -45682,11 +45710,19 @@ var AgentRelay = class {
       } else if (!this.clientOptions.env.RELAY_API_KEY) {
         this.clientOptions.env.RELAY_API_KEY = envKey;
       }
+      this.wireRelaycastBaseUrl();
       return;
     }
     if (!this.clientOptions.env) {
       this.clientOptions.env = { ...process.env };
     }
+    this.wireRelaycastBaseUrl();
+  }
+  /** Inject relaycastBaseUrl into broker env. Explicit option wins over inherited env. */
+  wireRelaycastBaseUrl() {
+    if (this.relaycastBaseUrl && this.clientOptions.env) {
+      this.clientOptions.env.RELAYCAST_BASE_URL = this.relaycastBaseUrl;
+    }
   }
   async ensureStarted() {
     if (this.client)
@@ -45849,12 +45885,31 @@ var AgentRelay = class {
           name,
           reason: releaseOptions.reason
         };
+        if (!relay.knownAgents.has(name)) {
+          await relay.invokeLifecycleHook(releaseOptions.onStart, releaseContext, `release("${name}") onStart`);
+          await relay.invokeLifecycleHook(releaseOptions.onSuccess, releaseContext, `release("${name}") onSuccess`);
+          return;
+        }
         const client = await relay.ensureStarted();
         await relay.invokeLifecycleHook(releaseOptions.onStart, releaseContext, `release("${name}") onStart`);
         try {
           await client.release(name, releaseOptions.reason);
           await relay.invokeLifecycleHook(releaseOptions.onSuccess, releaseContext, `release("${name}") onSuccess`);
         } catch (error95) {
+          if (error95 instanceof AgentRelayProtocolError && error95.code === "agent_not_found") {
+            relay.exitedAgents.add(name);
+            relay.readyAgents.delete(name);
+            relay.messageReadyAgents.delete(name);
+            relay.idleAgents.delete(name);
+            relay.knownAgents.delete(name);
+            relay.outputListeners.delete(name);
+            relay.exitResolvers.get(name)?.resolve("released");
+            relay.exitResolvers.delete(name);
+            relay.idleResolvers.get(name)?.resolve("exited");
+            relay.idleResolvers.delete(name);
+            await relay.invokeLifecycleHook(releaseOptions.onSuccess, releaseContext, `release("${name}") onSuccess`);
+            return;
+          }
           await relay.invokeLifecycleHook(releaseOptions.onError, {
             ...releaseContext,
             error: error95
@@ -45996,6 +46051,7 @@ var AgentRelay = class {
             task,
             model: options?.model,
             cwd: options?.cwd,
+            skipRelayPrompt: options?.skipRelayPrompt,
             onStart: options?.onStart,
             onSuccess: options?.onSuccess,
             onError: options?.onError
@@ -46017,7 +46073,8 @@ var AgentRelay = class {
             transport: "headless",
             args,
             channels,
-            task
+            task,
+            skipRelayPrompt: options?.skipRelayPrompt
           });
         } catch (error95) {
           await this.invokeLifecycleHook(options?.onError, {
@@ -47242,7 +47299,7 @@ var WorkflowTrajectory = class {
       id,
       version: 1,
       task: {
-        title: `${workflowName} run #${this.runId.slice(0, 8)}`,
+        title: workflowName,
         source: { system: "workflow-runner", id: this.runId }
       },
       status: "active",
@@ -47296,6 +47353,8 @@ var WorkflowTrajectory = class {
     if (participants?.reviewer) {
       await this.registerAgent(participants.reviewer, "reviewer");
     }
+    this.closeCurrentChapter();
+    this.openChapter(`Execution: ${step.name}`, agent);
     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();
@@ -47449,12 +47508,24 @@ var WorkflowTrajectory = class {
     await this.moveToCompleted();
   }
   /** Abandon the trajectory. */
-  async abandon(reason) {
+  async abandon(reason, meta5) {
     if (!this.enabled || !this.trajectory)
       return;
+    const elapsed = Date.now() - this.startTime;
+    const elapsedStr = elapsed > 6e4 ? `${Math.round(elapsed / 6e4)} minutes` : `${Math.round(elapsed / 1e3)} seconds`;
+    const summary = meta5?.summary ?? `Workflow abandoned: ${reason}`;
+    this.openRetrospective();
+    this.addEvent("reflection", `${summary} (abandoned after ${elapsedStr})`, "high");
     this.addEvent("error", `Workflow abandoned: ${reason}`, "high");
     this.trajectory.status = "abandoned";
     this.trajectory.completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    this.trajectory.retrospective = {
+      summary,
+      approach: `${this.swarmPattern} workflow (${this.trajectory.agents.filter((a) => a.role !== "workflow-runner").length} agents)`,
+      confidence: meta5?.confidence ?? 0,
+      learnings: meta5?.learnings,
+      challenges: meta5?.challenges
+    };
     this.closeCurrentChapter();
     await this.flush();
     await this.moveToCompleted();
@@ -47613,6 +47684,16 @@ var WorkflowTrajectory = class {
 };
 
 // packages/sdk/dist/workflows/runner.js
+var SpawnExitError = class extends Error {
+  exitCode;
+  exitSignal;
+  constructor(message, exitCode, exitSignal) {
+    super(message);
+    this.name = "SpawnExitError";
+    this.exitCode = exitCode;
+    this.exitSignal = exitSignal ?? void 0;
+  }
+};
 var _resolvedCursorCli;
 function resolveCursorCli() {
   if (_resolvedCursorCli !== void 0)
@@ -47656,6 +47737,8 @@ var WorkflowRunner = class _WorkflowRunner {
   activeAgentHandles = /* @__PURE__ */ new Map();
   // PTY-based output capture: accumulate terminal output per-agent
   ptyOutputBuffers = /* @__PURE__ */ new Map();
+  /** Snapshot of PTY output from the most recent failed attempt, keyed by step name. */
+  lastFailedStepOutput = /* @__PURE__ */ new Map();
   ptyListeners = /* @__PURE__ */ new Map();
   ptyLogStreams = /* @__PURE__ */ new Map();
   /** Path to workers.json so `agents:kill` can find workflow-spawned agents */
@@ -48383,7 +48466,10 @@ ${err.suggestion}`);
   // ── Execution ───────────────────────────────────────────────────────────
   /** Execute a named workflow from a validated config. */
   async execute(config3, workflowName, vars) {
+    this.abortController = new AbortController();
+    this.paused = false;
     const resolved = vars ? this.resolveVariables(config3, vars) : config3;
+    this.validateConfig(resolved);
     const pathResult = this.resolvePathDefinitions(resolved.paths, this.cwd);
     if (pathResult.errors.length > 0) {
       throw new Error(`Path validation failed:
@@ -48446,6 +48532,8 @@ ${err.suggestion}`);
   }
   /** Resume a previously paused or partially completed run. */
   async resume(runId, vars) {
+    this.abortController = new AbortController();
+    this.paused = false;
     const run = await this.db.getRun(runId);
     if (!run) {
       throw new Error(`Run "${runId}" not found`);
@@ -48492,8 +48580,6 @@ ${err.suggestion}`);
   async runWorkflowCore(input) {
     const { run, workflow: workflow2, config: config3, stepStates, isResume } = input;
     const runId = run.id;
-    this.abortController = new AbortController();
-    this.paused = false;
     this.currentConfig = config3;
     this.currentRunId = runId;
     this.runStartTime = Date.now();
@@ -48517,14 +48603,18 @@ ${err.suggestion}`);
         config3.swarm.channel = channel;
         await this.db.updateRun(runId, { config: config3 });
       }
-      if (!this.executor) {
-        this.log("Resolving Relaycast API key...");
-        await this.ensureRelaycastApiKey(channel);
-        this.log("API key resolved");
-        if (this.relayApiKeyAutoCreated && this.relayApiKey) {
-          this.log(`Workspace created \u2014 follow this run in Relaycast:`);
-          this.log(`  Observer: https://agentrelay.dev/observer?key=${this.relayApiKey}`);
-          this.log(`  Channel: ${channel}`);
+      const relaycastDisabled = this.relayOptions.env?.AGENT_RELAY_WORKFLOW_DISABLE_RELAYCAST === "1";
+      const requiresBroker = !this.executor && workflow2.steps.some((step) => step.type !== "deterministic" && step.type !== "worktree");
+      if (requiresBroker) {
+        if (!relaycastDisabled) {
+          this.log("Resolving Relaycast API key...");
+          await this.ensureRelaycastApiKey(channel);
+          this.log("API key resolved");
+          if (this.relayApiKeyAutoCreated && this.relayApiKey) {
+            this.log(`Workspace created \u2014 follow this run in Relaycast:`);
+            this.log(`  Observer: https://agentrelay.dev/observer?key=${this.relayApiKey}`);
+            this.log(`  Channel: ${channel}`);
+          }
         }
         this.log("Starting broker...");
         const brokerBaseName = import_node_path8.default.basename(this.cwd) || "workflow";
@@ -48532,7 +48622,7 @@ ${err.suggestion}`);
         this.relay = new AgentRelay({
           ...this.relayOptions,
           brokerName,
-          channels: [channel],
+          channels: relaycastDisabled ? [] : [channel],
           env: this.getRelayEnv(),
           // Workflows spawn agents across multiple waves; each spawn requires a PTY +
           // Relaycast registration. 60s is too tight when the broker is saturated with
@@ -48580,6 +48670,18 @@ ${err.suggestion}`);
           }
         };
         this.relay.onMessageReceived = (msg) => {
+          this.emit({
+            type: "broker:event",
+            runId,
+            event: {
+              kind: "relay_inbound",
+              event_id: msg.eventId,
+              from: msg.from,
+              target: msg.to,
+              body: msg.text,
+              thread_id: msg.threadId
+            }
+          });
           const body = msg.text.length > 120 ? msg.text.slice(0, 117) + "..." : msg.text;
           const fromShort = msg.from.replace(/-[a-f0-9]{6,}$/, "");
           const toShort = msg.to.replace(/-[a-f0-9]{6,}$/, "");
@@ -48590,18 +48692,59 @@ ${err.suggestion}`);
           }
         };
         this.relay.onAgentSpawned = (agent) => {
+          this.emit({
+            type: "broker:event",
+            runId,
+            event: {
+              kind: "agent_spawned",
+              name: agent.name,
+              runtime: agent.runtime
+            }
+          });
           if (!this.activeAgentHandles.has(agent.name)) {
             this.log(`[spawned] ${agent.name} (${agent.runtime})`);
           }
         };
+        this.relay.onAgentReleased = (agent) => {
+          this.emit({
+            type: "broker:event",
+            runId,
+            event: {
+              kind: "agent_released",
+              name: agent.name
+            }
+          });
+        };
         this.relay.onAgentExited = (agent) => {
+          this.emit({
+            type: "broker:event",
+            runId,
+            event: {
+              kind: "agent_exited",
+              name: agent.name,
+              code: agent.exitCode,
+              signal: agent.exitSignal
+            }
+          });
           this.lastActivity.delete(agent.name);
           this.lastIdleLog.delete(agent.name);
           if (!this.activeAgentHandles.has(agent.name)) {
             this.log(`[exited] ${agent.name} (code: ${agent.exitCode ?? "?"})`);
           }
         };
+        this.relay.onDeliveryUpdate = (event) => {
+          this.emit({ type: "broker:event", runId, event });
+        };
         this.relay.onAgentIdle = ({ name, idleSecs }) => {
+          this.emit({
+            type: "broker:event",
+            runId,
+            event: {
+              kind: "agent_idle",
+              name,
+              idle_secs: idleSecs
+            }
+          });
           const bucket = Math.floor(idleSecs / 30) * 30;
           if (bucket >= 30 && this.lastIdleLog.get(name) !== bucket) {
             this.lastIdleLog.set(name, bucket);
@@ -48614,17 +48757,19 @@ ${err.suggestion}`);
         this.unsubBrokerStderr = this.relay.onBrokerStderr((line) => {
           console.log(`[broker] ${line}`);
         });
-        this.log(`Creating channel: ${channel}...`);
-        if (isResume) {
-          await this.createAndJoinRelaycastChannel(channel);
-        } else {
-          await this.createAndJoinRelaycastChannel(channel, workflow2.description);
-        }
-        this.log("Channel ready");
-        if (isResume) {
-          this.postToChannel(`Workflow **${workflow2.name}** resumed \u2014 ${pendingCount} pending steps`);
-        } else {
-          this.postToChannel(`Workflow **${workflow2.name}** started \u2014 ${workflow2.steps.length} steps, pattern: ${config3.swarm.pattern}`);
+        if (!relaycastDisabled) {
+          this.log(`Creating channel: ${channel}...`);
+          if (isResume) {
+            await this.createAndJoinRelaycastChannel(channel);
+          } else {
+            await this.createAndJoinRelaycastChannel(channel, workflow2.description);
+          }
+          this.log("Channel ready");
+          if (isResume) {
+            this.postToChannel(`Workflow **${workflow2.name}** resumed \u2014 ${pendingCount} pending steps`);
+          } else {
+            this.postToChannel(`Workflow **${workflow2.name}** started \u2014 ${workflow2.steps.length} steps, pattern: ${config3.swarm.pattern}`);
+          }
         }
       }
       const agentMap = /* @__PURE__ */ new Map();
@@ -48636,7 +48781,9 @@ ${err.suggestion}`);
       }
       this.log(`Executing ${workflow2.steps.length} steps (pattern: ${config3.swarm.pattern})`);
       await this.executeSteps(workflow2, stepStates, agentMap, config3.errorHandling, runId);
-      const allCompleted = [...stepStates.values()].every((s) => s.row.status === "completed" || s.row.status === "skipped");
+      const errorStrategy = config3.errorHandling?.strategy ?? workflow2.onError ?? "fail-fast";
+      const continueOnError = errorStrategy === "continue" || errorStrategy === "skip";
+      const allCompleted = [...stepStates.values()].every((s) => s.row.status === "completed" || s.row.status === "skipped" || continueOnError && s.row.status === "failed");
       if (allCompleted) {
         this.log("Workflow completed successfully");
         await this.updateRunStatus(runId, "completed");
@@ -48656,24 +48803,52 @@ ${err.suggestion}`);
         await this.updateRunStatus(runId, "failed", errorMsg);
         this.emit({ type: "run:failed", runId, error: errorMsg });
         const outcomes = this.collectOutcomes(stepStates, workflow2.steps);
+        const summary = this.trajectory.buildRunSummary(outcomes);
+        const confidence = this.trajectory.computeConfidence(outcomes);
+        const learnings = this.trajectory.extractLearnings(outcomes);
+        const challenges = this.trajectory.extractChallenges(outcomes);
         this.postFailureReport(workflow2.name, outcomes, errorMsg);
         this.logRunSummary(workflow2.name, outcomes, runId);
-        await this.trajectory.abandon(errorMsg);
+        await this.trajectory.abandon(errorMsg, {
+          summary,
+          confidence,
+          learnings,
+          challenges
+        });
       }
     } catch (err) {
       const errorMsg = err instanceof Error ? err.message : String(err);
       const status = !isResume && this.abortController?.signal.aborted ? "cancelled" : "failed";
       await this.updateRunStatus(runId, status, errorMsg);
       if (status === "cancelled") {
+        for (const [stepName, state] of stepStates) {
+          if (state.row.status === "pending" || state.row.status === "running") {
+            state.row.status = "failed";
+            state.row.error = "Cancelled";
+            await this.db.updateStep(state.row.id, {
+              status: "failed",
+              error: "Cancelled",
+              updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+            });
+            this.emit({ type: "step:failed", runId, stepName, error: "Cancelled" });
+          }
+        }
         this.emit({ type: "run:cancelled", runId });
         this.postToChannel(`Workflow **${workflow2.name}** cancelled`);
         await this.trajectory.abandon("Cancelled by user");
       } else {
         this.emit({ type: "run:failed", runId, error: errorMsg });
         this.postToChannel(`Workflow failed: ${errorMsg}`);
-        await this.trajectory.abandon(errorMsg);
+        const outcomes = this.collectOutcomes(stepStates, workflow2.steps);
+        await this.trajectory.abandon(errorMsg, {
+          summary: this.trajectory.buildRunSummary(outcomes),
+          confidence: this.trajectory.computeConfidence(outcomes),
+          learnings: this.trajectory.extractLearnings(outcomes),
+          challenges: this.trajectory.extractChallenges(outcomes)
+        });
       }
     } finally {
+      this.lastFailedStepOutput.clear();
       for (const stream of this.ptyLogStreams.values())
         stream.end();
       this.ptyLogStreams.clear();
@@ -48684,9 +48859,11 @@ ${err.suggestion}`);
       if (this.relay) {
         this.relay.onMessageReceived = null;
         this.relay.onAgentSpawned = null;
+        this.relay.onAgentReleased = null;
         this.relay.onAgentExited = null;
         this.relay.onAgentIdle = null;
         this.relay.onWorkerOutput = null;
+        this.relay.onDeliveryUpdate = null;
       }
       this.lastIdleLog.clear();
       this.lastActivity.clear();
@@ -48907,7 +49084,7 @@ ${trimmedOutput.slice(0, 200)}`);
   }
   async executeStep(step, stepStates, agentMap, errorHandling, runId) {
     if (this.isDeterministicStep(step)) {
-      return this.executeDeterministicStep(step, stepStates, runId);
+      return this.executeDeterministicStep(step, stepStates, runId, errorHandling);
     }
     if (this.isWorktreeStep(step)) {
       return this.executeWorktreeStep(step, stepStates, runId);
@@ -48918,131 +49095,154 @@ ${trimmedOutput.slice(0, 200)}`);
    * Execute a deterministic step (shell command).
    * Fast, reliable, $0 LLM cost.
    */
-  async executeDeterministicStep(step, stepStates, runId) {
+  async executeDeterministicStep(step, stepStates, runId, errorHandling) {
     const state = stepStates.get(step.name);
     if (!state)
       throw new Error(`Step state not found: ${step.name}`);
-    this.checkAborted();
-    state.row.status = "running";
-    state.row.startedAt = (/* @__PURE__ */ new Date()).toISOString();
-    await this.db.updateStep(state.row.id, {
-      status: "running",
-      startedAt: state.row.startedAt,
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    });
-    this.emit({ type: "step:started", runId, stepName: step.name });
-    this.postToChannel(`**[${step.name}]** Started (deterministic)`);
-    const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
-    let resolvedCommand = this.interpolateStepTask(step.command ?? "", stepOutputContext);
-    resolvedCommand = resolvedCommand.replace(/\{\{([\w][\w.\-]*)\}\}/g, (_match, key) => {
-      if (key.startsWith("steps."))
-        return _match;
-      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, 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)}`);
-        }
-        const output2 = step.captureOutput !== false ? result.output : `Command completed (exit code ${result.exitCode})`;
-        state.row.status = "completed";
-        state.row.output = output2;
-        state.row.completedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const maxRetries = step.retries ?? errorHandling?.maxRetries ?? 0;
+    const retryDelay = errorHandling?.retryDelayMs ?? 1e3;
+    let lastError;
+    for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
+      this.checkAborted();
+      if (attempt > 0) {
+        this.emit({ type: "step:retrying", runId, stepName: step.name, attempt });
+        this.postToChannel(`**[${step.name}]** Retrying (attempt ${attempt + 1}/${maxRetries + 1})`);
+        state.row.retryCount = attempt;
         await this.db.updateStep(state.row.id, {
-          status: "completed",
-          output: output2,
-          completedAt: state.row.completedAt,
+          retryCount: attempt,
           updatedAt: (/* @__PURE__ */ new Date()).toISOString()
         });
-        await this.persistStepOutput(runId, step.name, output2);
-        this.emit({ type: "step:completed", runId, stepName: step.name, output: output2 });
-        return;
+        await this.delay(retryDelay);
       }
-      const output = await new Promise((resolve3, reject) => {
-        const child = (0, import_node_child_process3.spawn)("sh", ["-c", resolvedCommand], {
-          stdio: "pipe",
-          cwd: stepCwd,
-          env: { ...process.env }
-        });
-        const stdoutChunks = [];
-        const stderrChunks = [];
-        const abortSignal = this.abortController?.signal;
-        let abortHandler;
-        if (abortSignal && !abortSignal.aborted) {
-          abortHandler = () => {
-            child.kill("SIGTERM");
-            setTimeout(() => child.kill("SIGKILL"), 5e3);
-          };
-          abortSignal.addEventListener("abort", abortHandler, { once: true });
-        }
-        let timedOut = false;
-        let timer;
-        if (step.timeoutMs) {
-          timer = setTimeout(() => {
-            timedOut = true;
-            child.kill("SIGTERM");
-            setTimeout(() => child.kill("SIGKILL"), 5e3);
-          }, step.timeoutMs);
-        }
-        child.stdout?.on("data", (chunk) => {
-          stdoutChunks.push(chunk.toString());
-        });
-        child.stderr?.on("data", (chunk) => {
-          stderrChunks.push(chunk.toString());
-        });
-        child.on("close", (code) => {
-          if (timer)
-            clearTimeout(timer);
-          if (abortHandler && abortSignal) {
-            abortSignal.removeEventListener("abort", abortHandler);
+      state.row.status = "running";
+      state.row.startedAt = (/* @__PURE__ */ new Date()).toISOString();
+      await this.db.updateStep(state.row.id, {
+        status: "running",
+        startedAt: state.row.startedAt,
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      this.emit({ type: "step:started", runId, stepName: step.name });
+      this.postToChannel(`**[${step.name}]** Started (deterministic)`);
+      const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
+      let resolvedCommand = this.interpolateStepTask(step.command ?? "", stepOutputContext);
+      resolvedCommand = resolvedCommand.replace(/\{\{([\w][\w.\-]*)\}\}/g, (_match, key) => {
+        if (key.startsWith("steps."))
+          return _match;
+        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, 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)}`);
           }
-          if (abortSignal?.aborted) {
-            reject(new Error(`Step "${step.name}" aborted`));
-            return;
+          const output2 = step.captureOutput !== false ? result.output : `Command completed (exit code ${result.exitCode})`;
+          if (step.verification) {
+            this.runVerification(step.verification, output2, step.name);
           }
-          if (timedOut) {
-            reject(new Error(`Step "${step.name}" timed out (no step timeout set, check global swarm.timeoutMs)`));
-            return;
+          state.row.status = "completed";
+          state.row.output = output2;
+          state.row.completedAt = (/* @__PURE__ */ new Date()).toISOString();
+          await this.db.updateStep(state.row.id, {
+            status: "completed",
+            output: output2,
+            completedAt: state.row.completedAt,
+            updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          await this.persistStepOutput(runId, step.name, output2);
+          this.emit({ type: "step:completed", runId, stepName: step.name, output: output2 });
+          return;
+        }
+        const output = await new Promise((resolve3, reject) => {
+          const child = (0, import_node_child_process3.spawn)("sh", ["-c", resolvedCommand], {
+            stdio: "pipe",
+            cwd: stepCwd,
+            env: { ...process.env }
+          });
+          const stdoutChunks = [];
+          const stderrChunks = [];
+          const abortSignal = this.abortController?.signal;
+          let abortHandler;
+          if (abortSignal && !abortSignal.aborted) {
+            abortHandler = () => {
+              child.kill("SIGTERM");
+              setTimeout(() => child.kill("SIGKILL"), 5e3);
+            };
+            abortSignal.addEventListener("abort", abortHandler, { once: true });
           }
-          const stdout = stdoutChunks.join("");
-          const stderr = stderrChunks.join("");
-          const failOnError = step.failOnError !== false;
-          if (failOnError && code !== 0 && code !== null) {
-            reject(new Error(`Command failed with exit code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ""}`));
-            return;
+          let timedOut = false;
+          let timer;
+          if (step.timeoutMs) {
+            timer = setTimeout(() => {
+              timedOut = true;
+              child.kill("SIGTERM");
+              setTimeout(() => child.kill("SIGKILL"), 5e3);
+            }, step.timeoutMs);
           }
-          resolve3(step.captureOutput !== false ? stdout : `Command completed (exit code ${code ?? 0})`);
+          child.stdout?.on("data", (chunk) => {
+            stdoutChunks.push(chunk.toString());
+          });
+          child.stderr?.on("data", (chunk) => {
+            stderrChunks.push(chunk.toString());
+          });
+          child.on("close", (code) => {
+            if (timer)
+              clearTimeout(timer);
+            if (abortHandler && abortSignal) {
+              abortSignal.removeEventListener("abort", abortHandler);
+            }
+            if (abortSignal?.aborted) {
+              reject(new Error(`Step "${step.name}" aborted`));
+              return;
+            }
+            if (timedOut) {
+              reject(new Error(`Step "${step.name}" timed out (no step timeout set, check global swarm.timeoutMs)`));
+              return;
+            }
+            const stdout = stdoutChunks.join("");
+            const stderr = stderrChunks.join("");
+            const failOnError = step.failOnError !== false;
+            if (failOnError && code !== 0 && code !== null) {
+              reject(new Error(`Command failed with exit code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ""}`));
+              return;
+            }
+            resolve3(step.captureOutput !== false ? stdout : `Command completed (exit code ${code ?? 0})`);
+          });
+          child.on("error", (err) => {
+            if (timer)
+              clearTimeout(timer);
+            if (abortHandler && abortSignal) {
+              abortSignal.removeEventListener("abort", abortHandler);
+            }
+            reject(new Error(`Failed to execute command: ${err.message}`));
+          });
         });
-        child.on("error", (err) => {
-          if (timer)
-            clearTimeout(timer);
-          if (abortHandler && abortSignal) {
-            abortSignal.removeEventListener("abort", abortHandler);
-          }
-          reject(new Error(`Failed to execute command: ${err.message}`));
+        if (step.verification) {
+          this.runVerification(step.verification, output, step.name);
+        }
+        state.row.status = "completed";
+        state.row.output = output;
+        state.row.completedAt = (/* @__PURE__ */ new Date()).toISOString();
+        await this.db.updateStep(state.row.id, {
+          status: "completed",
+          output,
+          completedAt: state.row.completedAt,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
         });
-      });
-      state.row.status = "completed";
-      state.row.output = output;
-      state.row.completedAt = (/* @__PURE__ */ new Date()).toISOString();
-      await this.db.updateStep(state.row.id, {
-        status: "completed",
-        output,
-        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 });
-    } catch (err) {
-      const errorMsg = err instanceof Error ? err.message : String(err);
-      this.postToChannel(`**[${step.name}]** Failed: ${errorMsg}`);
-      await this.markStepFailed(state, errorMsg, runId);
-      throw new Error(`Step "${step.name}" failed: ${errorMsg}`);
+        await this.persistStepOutput(runId, step.name, output);
+        this.emit({ type: "step:completed", runId, stepName: step.name, output });
+        return;
+      } catch (err) {
+        lastError = err instanceof Error ? err.message : String(err);
+      }
     }
+    const errorMsg = lastError ?? "Unknown error";
+    this.postToChannel(`**[${step.name}]** Failed: ${errorMsg}`);
+    await this.markStepFailed(state, errorMsg, runId);
+    throw new Error(`Step "${step.name}" failed: ${errorMsg}`);
   }
   /**
    * Execute a worktree step (git worktree setup).
@@ -49211,8 +49411,12 @@ ${trimmedOutput.slice(0, 200)}`);
     const retryDelay = errorHandling?.retryDelayMs ?? 1e3;
     const timeoutMs = step.timeoutMs ?? ownerDef.constraints?.timeoutMs ?? specialistDef.constraints?.timeoutMs ?? this.currentConfig?.swarm?.timeoutMs;
     let lastError;
+    let lastExitCode;
+    let lastExitSignal;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
       this.checkAborted();
+      lastExitCode = void 0;
+      lastExitSignal = void 0;
       if (attempt > 0) {
         this.emit({ type: "step:retrying", runId, stepName: step.name, attempt });
         this.postToChannel(`**[${step.name}]** Retrying (attempt ${attempt + 1}/${maxRetries + 1})`);
@@ -49252,6 +49456,15 @@ ${trimmedOutput.slice(0, 200)}`);
         });
         const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
         let resolvedTask = this.interpolateStepTask(step.task ?? "", stepOutputContext);
+        if (attempt > 0 && lastError) {
+          const priorOutput = (this.lastFailedStepOutput.get(step.name) ?? "").slice(-2e3);
+          resolvedTask = `[RETRY \u2014 Attempt ${attempt + 1}/${maxRetries + 1}]
+Previous attempt failed: ${lastError}
+` + (priorOutput ? `Previous output (last 2000 chars):
+${priorOutput}
+` : "") + `---
+${resolvedTask}`;
+        }
         if (specialistDef.interactive !== false || ownerDef.interactive !== false) {
           const nonInteractiveInfo = this.buildNonInteractiveAwareness(agentMap, stepStates);
           if (nonInteractiveInfo) {
@@ -49282,7 +49495,10 @@ ${trimmedOutput.slice(0, 200)}`);
           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);
+          const spawnResult = this.executor ? await this.executor.executeAgentStep(resolvedStep, effectiveOwner, ownerTask, timeoutMs) : await this.spawnAndWait(effectiveOwner, resolvedStep, timeoutMs);
+          const output = typeof spawnResult === "string" ? spawnResult : spawnResult.output;
+          lastExitCode = typeof spawnResult === "string" ? void 0 : spawnResult.exitCode;
+          lastExitSignal = typeof spawnResult === "string" ? void 0 : spawnResult.exitSignal;
           ownerElapsed = Date.now() - ownerStartTime;
           this.log(`[${step.name}] Owner "${effectiveOwner.name}" exited`);
           if (usesOwnerFlow) {
@@ -49292,7 +49508,7 @@ ${trimmedOutput.slice(0, 200)}`);
           ownerOutput = output;
         }
         if (step.verification) {
-          this.runVerification(step.verification, specialistOutput, step.name, resolvedTask);
+          this.runVerification(step.verification, specialistOutput, step.name, effectiveOwner.interactive === false ? void 0 : resolvedTask);
         }
         let combinedOutput = specialistOutput;
         if (usesOwnerFlow && reviewDef) {
@@ -49310,11 +49526,15 @@ ${trimmedOutput.slice(0, 200)}`);
           updatedAt: (/* @__PURE__ */ new Date()).toISOString()
         });
         await this.persistStepOutput(runId, step.name, combinedOutput);
-        this.emit({ type: "step:completed", runId, stepName: step.name, output: combinedOutput });
+        this.emit({ type: "step:completed", runId, stepName: step.name, output: combinedOutput, exitCode: lastExitCode, exitSignal: lastExitSignal });
         await this.trajectory?.stepCompleted(step, combinedOutput, attempt + 1);
         return;
       } catch (err) {
         lastError = err instanceof Error ? err.message : String(err);
+        if (err instanceof SpawnExitError) {
+          lastExitCode = err.exitCode;
+          lastExitSignal = err.exitSignal;
+        }
         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 });
@@ -49329,7 +49549,10 @@ ${trimmedOutput.slice(0, 200)}`);
       verificationValue
     });
     this.postToChannel(`**[${step.name}]** Failed: ${lastError ?? "Unknown error"}`);
-    await this.markStepFailed(state, lastError ?? "Unknown error", runId);
+    await this.markStepFailed(state, lastError ?? "Unknown error", runId, {
+      exitCode: lastExitCode,
+      exitSignal: lastExitSignal
+    });
     throw new Error(`Step "${step.name}" failed after ${maxRetries} retries: ${lastError ?? "Unknown error"}`);
   }
   injectStepOwnerContract(step, resolvedTask, ownerDef, specialistDef) {
@@ -49447,10 +49670,10 @@ Output exactly: STEP_COMPLETE:${step.name}`;
       throw error95;
     });
     const workerSettled = workerPromise.catch(() => void 0);
-    workerPromise.then((output) => {
+    workerPromise.then((result) => {
       workerReleased = true;
       this.postToChannel(`**[${step.name}]** Worker \`${workerRuntimeName}\` exited`);
-      if (step.verification?.type === "output_contains" && output.includes(step.verification.value)) {
+      if (step.verification?.type === "output_contains" && result.output.includes(step.verification.value)) {
         this.postToChannel(`**[${step.name}]** Verification gate observed: output contains ${JSON.stringify(step.verification.value)}`);
       }
     }).catch((error95) => {
@@ -49468,7 +49691,7 @@ Output exactly: STEP_COMPLETE:${step.name}`;
     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, {
+      const ownerResultObj = await this.spawnAndWait(supervised.owner, ownerStep, timeoutMs, {
         agentNameSuffix: "owner",
         onSpawned: ({ actualName }) => {
           this.supervisedRuntimeAgents.set(actualName, {
@@ -49482,9 +49705,10 @@ Output exactly: STEP_COMPLETE:${step.name}`;
         }
       });
       const ownerElapsed = Date.now() - ownerStartTime;
+      const ownerOutput = ownerResultObj.output;
       this.log(`[${step.name}] Owner "${supervised.owner.name}" exited`);
       this.assertOwnerCompletionMarker(step, ownerOutput, supervisorTask);
-      const specialistOutput = await workerPromise;
+      const specialistOutput = (await workerPromise).output;
       return { specialistOutput, ownerOutput, ownerElapsed };
     } catch (error95) {
       const message = error95 instanceof Error ? error95.message : String(error95);
@@ -49682,7 +49906,7 @@ Then output /exit.`;
       })();
     };
     try {
-      reviewOutput = await this.spawnAndWait(reviewerDef, reviewStep, safetyTimeoutMs, {
+      await this.spawnAndWait(reviewerDef, reviewStep, safetyTimeoutMs, {
         onSpawned: ({ agent }) => {
           reviewerHandle = agent;
         },
@@ -49862,7 +50086,7 @@ DO NOT:
     const stdoutChunks = [];
     const stderrChunks = [];
     try {
-      const output = await new Promise((resolve3, reject) => {
+      const { stdout: output, exitCode, exitSignal } = await new Promise((resolve3, reject) => {
         const child = (0, import_node_child_process3.spawn)(cmd, args, {
           stdio: ["ignore", "pipe", "pipe"],
           cwd: this.resolveAgentCwd(agentDef),
@@ -49908,7 +50132,7 @@ DO NOT:
             setTimeout(() => child.kill("SIGKILL"), 5e3);
           }, timeoutMs);
         }
-        child.on("close", (code) => {
+        child.on("close", (code, signal) => {
           clearInterval(heartbeat);
           if (timer)
             clearTimeout(timer);
@@ -49926,10 +50150,14 @@ DO NOT:
           }
           if (code !== 0 && code !== null) {
             const stderr = stderrChunks.join("");
-            reject(new Error(`Step "${step.name}" exited with code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ""}`));
+            reject(new SpawnExitError(`Step "${step.name}" exited with code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ""}`, code, signal));
             return;
           }
-          resolve3(stdout);
+          resolve3({
+            stdout,
+            exitCode: code ?? void 0,
+            exitSignal: signal ?? void 0
+          });
         });
         child.on("error", (err) => {
           clearInterval(heartbeat);
@@ -49941,8 +50169,10 @@ DO NOT:
           reject(new Error(`Failed to spawn ${cmd}: ${err.message}`));
         });
       });
-      return output;
+      return { output, exitCode, exitSignal };
     } finally {
+      const combinedOutput = stdoutChunks.join("") + stderrChunks.join("");
+      this.lastFailedStepOutput.set(step.name, combinedOutput);
       stopHeartbeat?.();
       logStream.end();
       this.unregisterWorker(agentName);
@@ -50062,8 +50292,12 @@ DO NOT:
           throw new Error(`Step "${step.name}" timed out after ${timeoutMs ?? "unknown"}ms`);
         }
       }
+      if (exitResult === "force-released") {
+        throw new Error(`Step "${step.name}" failed \u2014 agent was force-released after exhausting idle nudges without completing`);
+      }
     } finally {
       ptyChunks = this.ptyOutputBuffers.get(agentName) ?? [];
+      this.lastFailedStepOutput.set(step.name, ptyChunks.join(""));
       stopHeartbeat?.();
       this.activeAgentHandles.delete(agentName);
       this.ptyOutputBuffers.delete(agentName);
@@ -50081,9 +50315,13 @@ DO NOT:
       output = ptyChunks.join("");
     } else {
       const summaryPath = import_node_path8.default.join(this.summaryDir, `${step.name}.md`);
-      output = (0, import_node_fs4.existsSync)(summaryPath) ? await (0, import_promises3.readFile)(summaryPath, "utf-8") : exitResult === "timeout" ? "Agent completed (released after idle timeout)" : exitResult === "released" ? "Agent completed (force-released after idle nudging)" : `Agent exited (${exitResult})`;
+      output = (0, import_node_fs4.existsSync)(summaryPath) ? await (0, import_promises3.readFile)(summaryPath, "utf-8") : exitResult === "timeout" ? "Agent completed (released after idle timeout)" : exitResult === "released" ? "Agent completed (idle \u2014 treated as done)" : `Agent exited (${exitResult})`;
     }
-    return output;
+    return {
+      output,
+      exitCode: agent?.exitCode,
+      exitSignal: agent?.exitSignal
+    };
   }
   // ── Idle nudging ────────────────────────────────────────────────────────
   /** Patterns where a hub agent coordinates spoke agents. */
@@ -50142,7 +50380,7 @@ DO NOT:
       if (exitResult !== "timeout") {
         return exitResult;
       }
-      if (remaining !== void 0 && Date.now() - startTime >= remaining) {
+      if (timeoutMs !== void 0 && Date.now() - startTime >= timeoutMs) {
         return "timeout";
       }
       if (nudgeCount < maxNudges) {
@@ -50155,7 +50393,7 @@ DO NOT:
       this.postToChannel(`**[${step.name}]** Agent \`${agent.name}\` still idle after ${nudgeCount} nudge(s) \u2014 force-releasing`);
       this.emit({ type: "step:force-released", runId: this.currentRunId ?? "", stepName: step.name });
       await agent.release();
-      return "released";
+      return "force-released";
     }
   }
   /**
@@ -50250,7 +50488,7 @@ DO NOT:
     }
     await this.db.updateRun(runId, patch);
   }
-  async markStepFailed(state, error95, runId) {
+  async markStepFailed(state, error95, runId, exitInfo) {
     state.row.status = "failed";
     state.row.error = error95;
     state.row.completedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -50260,7 +50498,14 @@ DO NOT:
       completedAt: state.row.completedAt,
       updatedAt: (/* @__PURE__ */ new Date()).toISOString()
     });
-    this.emit({ type: "step:failed", runId, stepName: state.row.stepName, error: error95 });
+    this.emit({
+      type: "step:failed",
+      runId,
+      stepName: state.row.stepName,
+      error: error95,
+      exitCode: exitInfo?.exitCode,
+      exitSignal: exitInfo?.exitSignal
+    });
   }
   async markDownstreamSkipped(failedStepName, allSteps, stepStates, runId) {
     const queue = [failedStepName];