@agent-relay/sdk 4.0.0 → 4.0.1

package/dist/workflows/runner.js

@@ -18,13 +18,68 @@ import { resolveCliSync } from '../cli-resolver.js';
 import { loadCustomSteps, resolveAllCustomSteps, validateCustomStepsUsage, CustomStepsParseError, CustomStepResolutionError, } from './custom-steps.js';
 import { collectCliSession } from './cli-session-collector.js';
 import { executeApiStep } from './api-executor.js';
+import { ChannelMessenger } from './channel-messenger.js';
 import { InMemoryWorkflowDb } from './memory-db.js';
+import { buildCommand as buildProcessCommand, spawnProcess } from './process-spawner.js';
 import { formatRunSummaryTable } from './run-summary-table.js';
+import { StepExecutor as WorkflowStepLifecycleExecutor, } from './step-executor.js';
+import { interpolateStepTask as interpolateStepTaskTemplate, resolveDotPath as resolveTemplateDotPath, resolveTemplate, TemplateResolver, } from './template-resolver.js';
 import { WorkflowTrajectory } from './trajectory.js';
+import { runVerification, stripInjectedTaskEcho, WorkflowCompletionError, } from './verification.js';
 // ── AgentRelay SDK imports ──────────────────────────────────────────────────
 // Import from sub-paths to avoid pulling in the full @relaycast/sdk dependency.
 import { AgentRelay } from '../relay.js';
 import { RelayCast, RelayError } from '@relaycast/sdk';
+// ── Environment filtering ──────────────────────────────────────────────────
+/** Keys explicitly allowed to propagate to spawned child processes. */
+const ENV_ALLOWLIST = new Set([
+    'PATH',
+    'HOME',
+    'USER',
+    'SHELL',
+    'LANG',
+    'TERM',
+    'TMPDIR',
+    'TZ',
+    'NODE_ENV',
+    'NODE_PATH',
+    'NODE_OPTIONS',
+    'NODE_EXTRA_CA_CERTS',
+    'RUST_LOG',
+    'RUST_BACKTRACE',
+    'RELAY_API_KEY',
+    'RELAYCAST_BASE_URL',
+    'AGENT_RELAY_DASHBOARD_PORT',
+    'AGENT_RELAY_RUN_ID_FILE',
+    'EDITOR',
+    'VISUAL',
+    'GIT_AUTHOR_NAME',
+    'GIT_AUTHOR_EMAIL',
+    'GIT_COMMITTER_NAME',
+    'GIT_COMMITTER_EMAIL',
+    'HTTPS_PROXY',
+    'HTTP_PROXY',
+    'NO_PROXY',
+    'https_proxy',
+    'http_proxy',
+    'no_proxy',
+    'XDG_CONFIG_HOME',
+    'XDG_DATA_HOME',
+    'XDG_CACHE_HOME',
+]);
+/** Return a filtered copy of process.env containing only allowlisted keys. */
+function filteredEnv(extra) {
+    const env = {};
+    for (const key of ENV_ALLOWLIST) {
+        if (process.env[key] !== undefined) {
+            env[key] = process.env[key];
+        }
+    }
+    if (extra) {
+        Object.assign(env, extra);
+    }
+    return env;
+}
 /** Error carrying exit code/signal from a failed subprocess spawn. */
 class SpawnExitError extends Error {
     exitCode;
@@ -36,14 +91,6 @@ class SpawnExitError extends Error {
         this.exitSignal = exitSignal ?? undefined;
     }
 }
-class WorkflowCompletionError extends Error {
-    completionReason;
-    constructor(message, completionReason) {
-        super(message);
-        this.name = 'WorkflowCompletionError';
-        this.completionReason = completionReason;
-    }
-}
 // ── CLI resolution ───────────────────────────────────────────────────────────
 /**
  * Resolve `cursor` to the concrete cursor agent binary available in PATH.
@@ -63,6 +110,8 @@ export class WorkflowRunner {
     summaryDir;
     executor;
     envSecrets;
+    templateResolver;
+    channelMessenger;
     /** @internal exposed for CLI signal-handler shutdown only */
     relay;
     relaycast;
@@ -125,6 +174,8 @@ export class WorkflowRunner {
         this.workersPath = path.join(this.cwd, '.agent-relay', 'team', 'workers.json');
         this.executor = options.executor;
         this.envSecrets = options.envSecrets;
+        this.templateResolver = new TemplateResolver();
+        this.channelMessenger = new ChannelMessenger({ postFn: (text) => this.postToChannel(text) });
     }
     // ── Path resolution ─────────────────────────────────────────────────────
     /** Expand environment variables like $HOME or $VAR in a path string. */
@@ -251,11 +302,10 @@ export class WorkflowRunner {
         this.rememberStepSignalSender(stepName, 'worker', workerSender);
     }
     rememberStepSignalSender(stepName, participant, ...senders) {
-        const participants = this.stepSignalParticipants.get(stepName) ??
-            {
-                ownerSenders: new Set(),
-                workerSenders: new Set(),
-            };
+        const participants = this.stepSignalParticipants.get(stepName) ?? {
+            ownerSenders: new Set(),
+            workerSenders: new Set(),
+        };
         this.stepSignalParticipants.set(stepName, participants);
         const target = participant === 'owner' ? participants.ownerSenders : participants.workerSenders;
         for (const sender of senders) {
@@ -275,11 +325,7 @@ export class WorkflowRunner {
         return undefined;
     }
     isSignalFromExpectedSender(stepName, signal) {
-        const expectedParticipant = signal.kind === 'worker_done'
-            ? 'worker'
-            : signal.kind === 'lead_done'
-                ? 'owner'
-                : undefined;
+        const expectedParticipant = signal.kind === 'worker_done' ? 'worker' : signal.kind === 'lead_done' ? 'owner' : undefined;
         if (!expectedParticipant)
             return true;
         const participants = this.stepSignalParticipants.get(stepName);
@@ -499,7 +545,9 @@ export class WorkflowRunner {
         return undefined;
     }
     uniqueEvidenceRoots(roots) {
-        return [...new Set(roots.filter((root) => Boolean(root)).map((root) => path.resolve(root)))];
+        return [
+            ...new Set(roots.filter((root) => Boolean(root)).map((root) => path.resolve(root))),
+        ];
     }
     captureFileSnapshot(root) {
         const snapshot = new Map();
@@ -611,9 +659,7 @@ export class WorkflowRunner {
         const evidence = this.getStepCompletionEvidence(stepName);
         if (!evidence)
             return undefined;
-        const signals = evidence.coordinationSignals
-            .slice(-6)
-            .map((signal) => signal.value ?? signal.text);
+        const signals = evidence.coordinationSignals.slice(-6).map((signal) => signal.value ?? signal.text);
         const channelPosts = evidence.channelPosts
             .filter((post) => post.completionRelevant)
             .slice(-3)
@@ -709,7 +755,7 @@ export class WorkflowRunner {
             return this.relayOptions.env;
         }
         return {
-            ...(this.relayOptions.env ?? process.env),
+            ...(this.relayOptions.env ?? filteredEnv()),
             RELAY_API_KEY: this.relayApiKey,
         };
     }
@@ -1253,71 +1299,13 @@ export class WorkflowRunner {
     // ── Template variable resolution ────────────────────────────────────────
     /** Resolve {{variable}} placeholders in all task strings. */
     resolveVariables(config, vars) {
-        const resolved = structuredClone(config);
-        for (const agent of resolved.agents) {
-            if (agent.task) {
-                agent.task = this.interpolate(agent.task, vars);
-            }
-        }
-        if (resolved.workflows) {
-            for (const wf of resolved.workflows) {
-                for (const step of wf.steps) {
-                    // Resolve variables in task (agent steps) and command (deterministic steps)
-                    if (step.task) {
-                        step.task = this.interpolate(step.task, vars);
-                    }
-                    if (step.command) {
-                        step.command = this.interpolate(step.command, vars);
-                    }
-                    // Resolve variables in integration step params
-                    if (step.params && typeof step.params === 'object') {
-                        for (const key of Object.keys(step.params)) {
-                            const val = step.params[key];
-                            if (typeof val === 'string') {
-                                step.params[key] = this.interpolate(val, vars);
-                            }
-                        }
-                    }
-                }
-            }
-        }
-        return resolved;
+        return this.templateResolver.resolveVariables(config, vars);
     }
     interpolate(template, vars) {
-        return template.replace(/\{\{([\w][\w.\-]*)\}\}/g, (_match, key) => {
-            // Skip step-output placeholders — they are resolved at execution time by interpolateStepTask()
-            if (key.startsWith('steps.')) {
-                return _match;
-            }
-            // Resolve dot-path variables like steps.plan.output
-            const value = this.resolveDotPath(key, vars);
-            if (value === undefined) {
-                throw new Error(`Unresolved variable: {{${key}}}`);
-            }
-            return String(value);
-        });
+        return resolveTemplate(template, vars);
     }
     resolveDotPath(key, vars) {
-        // Simple key — direct lookup
-        if (!key.includes('.')) {
-            return vars[key];
-        }
-        // Dot-path — walk into nested context
-        const parts = key.split('.');
-        let current = vars;
-        for (const part of parts) {
-            if (current === null || current === undefined || typeof current !== 'object') {
-                return undefined;
-            }
-            current = current[part];
-        }
-        if (current === undefined || current === null) {
-            return undefined;
-        }
-        if (typeof current === 'string' || typeof current === 'number' || typeof current === 'boolean') {
-            return current;
-        }
-        return String(current);
+        return resolveTemplateDotPath(key, vars);
     }
     /** Build a nested context from completed step outputs for {{steps.X.output}} resolution. */
     buildStepOutputContext(stepStates, runId) {
@@ -1339,14 +1327,84 @@ export class WorkflowRunner {
     }
     /** Interpolate step-output variables, silently skipping unresolved ones (they may be user vars). */
     interpolateStepTask(template, context) {
-        return template.replace(/\{\{(steps\.[\w\-]+\.output)\}\}/g, (_match, key) => {
-            const value = this.resolveDotPath(key, context);
-            if (value === undefined) {
-                // Leave unresolved — may not be an error if the template doesn't depend on prior steps
-                return _match;
-            }
-            return String(value);
-        });
+        return interpolateStepTaskTemplate(template, context);
+    }
+    createStepLifecycleExecutor(workflow, stepStates, agentMap, errorHandling, runId) {
+        // eslint-disable-next-line prefer-const -- circular: deps closure captures lifecycle before assignment
+        let lifecycle;
+        const deps = {
+            cwd: this.cwd,
+            runId,
+            templateResolver: this.templateResolver,
+            channelMessenger: this.channelMessenger,
+            verificationRunner: (check, output, stepName, injectedTaskText, options) => this.runVerification(check, output, stepName, injectedTaskText, options),
+            postToChannel: (text) => this.postToChannel(text),
+            persistStepRow: async (stepId, patch) => this.db.updateStep(stepId, patch),
+            persistStepOutput: async (lifecycleRunId, stepName, output) => this.persistStepOutput(lifecycleRunId, stepName, output),
+            loadStepOutput: (lifecycleRunId, stepName) => this.loadStepOutput(lifecycleRunId, stepName),
+            checkAborted: () => this.checkAborted(),
+            waitIfPaused: () => this.waitIfPaused(),
+            log: (message) => this.log(message),
+            onStepStarted: async (step) => {
+                this.emit({ type: 'step:started', runId, stepName: step.name });
+            },
+            onStepCompleted: async (step, state, result) => {
+                this.emit({
+                    type: 'step:completed',
+                    runId,
+                    stepName: step.name,
+                    output: result.output,
+                    exitCode: result.exitCode,
+                    exitSignal: result.exitSignal,
+                });
+                this.finalizeStepEvidence(step.name, result.status, state.row.completedAt, result.completionReason);
+            },
+            onStepFailed: async (step, state, result) => {
+                this.captureStepTerminalEvidence(step.name, {}, {
+                    exitCode: result.exitCode,
+                    exitSignal: result.exitSignal,
+                });
+                this.emit({
+                    type: 'step:failed',
+                    runId,
+                    stepName: step.name,
+                    error: result.error ?? 'Unknown error',
+                    exitCode: result.exitCode,
+                    exitSignal: result.exitSignal,
+                });
+                this.finalizeStepEvidence(step.name, 'failed', state.row.completedAt, result.completionReason);
+            },
+            executeStep: async (step, state) => {
+                await this.executeStep(step, state, stepStates, agentMap, errorHandling, runId, lifecycle);
+                return {
+                    status: state.row.status,
+                    output: state.row.output ?? '',
+                    completionReason: state.row.completionReason,
+                    retries: state.row.retryCount,
+                    error: state.row.error,
+                };
+            },
+            onBeginTrack: async (steps) => {
+                if (steps.length > 1 && this.trajectory) {
+                    await this.trajectory.beginTrack(steps.map((step) => step.name).join(', '));
+                }
+            },
+            onConverge: async (readySteps, batchOutcomes) => {
+                if (readySteps.length <= 1 || !this.trajectory?.shouldReflectOnConverge()) {
+                    return;
+                }
+                const completedNames = new Set(batchOutcomes.filter((outcome) => outcome.status === 'completed').map((outcome) => outcome.name));
+                const unblocked = workflow.steps
+                    .filter((step) => step.dependsOn?.some((dependency) => completedNames.has(dependency)))
+                    .filter((step) => stepStates.get(step.name)?.row.status === 'pending')
+                    .map((step) => step.name);
+                await this.trajectory.synthesizeAndReflect(readySteps.map((step) => step.name).join(' + '), batchOutcomes, unblocked.length > 0 ? unblocked : undefined);
+            },
+            markDownstreamSkipped: async (failedStepName) => this.markDownstreamSkipped(failedStepName, workflow.steps, stepStates, runId),
+            buildCompletionMode: (stepName, completionReason) => completionReason ? this.buildStepCompletionDecision(stepName, completionReason)?.mode : undefined,
+        };
+        lifecycle = new WorkflowStepLifecycleExecutor(deps);
+        return lifecycle;
     }
     // ── Execution ───────────────────────────────────────────────────────────
     /** Execute a named workflow from a validated config. */
@@ -1409,7 +1467,7 @@ export class WorkflowRunner {
                     : step.type === 'worktree'
                         ? (step.branch ?? '')
                         : step.type === 'integration'
-                            ? (`${step.integration}.${step.action}`)
+                            ? `${step.integration}.${step.action}`
                             : (step.task ?? ''),
                 dependsOn: step.dependsOn ?? [],
                 retryCount: 0,
@@ -1429,8 +1487,7 @@ export class WorkflowRunner {
             const transitiveDeps = this.collectTransitiveDeps(startFromName, resolvedWorkflow.steps);
             const skippedCount = transitiveDeps.size;
             // Determine which run ID to load cached outputs from
-            const cacheRunId = executeOptions.previousRunId
-                ?? this.findMostRecentRunWithSteps(transitiveDeps);
+            const cacheRunId = executeOptions.previousRunId ?? this.findMostRecentRunWithSteps(transitiveDeps);
             for (const depName of transitiveDeps) {
                 const state = stepStates.get(depName);
                 if (!state)
@@ -1920,8 +1977,6 @@ export class WorkflowRunner {
     // ── Step execution engine ─────────────────────────────────────────────
     async executeSteps(workflow, stepStates, agentMap, errorHandling, runId) {
         const rawStrategy = errorHandling?.strategy ?? workflow.onError ?? 'fail-fast';
-        // Map shorthand onError values to canonical strategy names.
-        // 'retry' maps to 'fail-fast' so downstream steps are properly skipped after retries exhaust.
         const strategy = rawStrategy === 'fail'
             ? 'fail-fast'
             : rawStrategy === 'skip'
@@ -1929,89 +1984,11 @@ export class WorkflowRunner {
                 : rawStrategy === 'retry'
                     ? 'fail-fast'
                     : rawStrategy;
-        // DAG-based execution: repeatedly find ready steps and run them in parallel
-        while (true) {
-            this.checkAborted();
-            await this.waitIfPaused();
-            const readySteps = this.findReadySteps(workflow.steps, stepStates);
-            if (readySteps.length === 0) {
-                // No steps ready — either all done or blocked
-                break;
-            }
-            // Begin a track chapter if multiple parallel steps are starting
-            if (readySteps.length > 1 && this.trajectory) {
-                const trackNames = readySteps.map((s) => s.name).join(', ');
-                await this.trajectory.beginTrack(trackNames);
-            }
-            // Stagger spawns when many steps are ready simultaneously.
-            // All agents still run concurrently once spawned — this only delays when
-            // each step's executeStep() begins, preventing Relaycast from receiving
-            // N simultaneous registration requests which causes spawn timeouts.
-            const STAGGER_THRESHOLD = 3;
-            const STAGGER_DELAY_MS = 2_000;
-            const results = await Promise.allSettled(readySteps.map((step, i) => {
-                const delay = readySteps.length > STAGGER_THRESHOLD ? i * STAGGER_DELAY_MS : 0;
-                if (delay === 0) {
-                    return this.executeStep(step, stepStates, agentMap, errorHandling, runId);
-                }
-                return new Promise((resolve) => setTimeout(resolve, delay)).then(() => this.executeStep(step, stepStates, agentMap, errorHandling, runId));
-            }));
-            // Collect outcomes from this batch for convergence reflection
-            const batchOutcomes = [];
-            for (let i = 0; i < results.length; i++) {
-                const result = results[i];
-                const step = readySteps[i];
-                const state = stepStates.get(step.name);
-                if (result.status === 'rejected') {
-                    const error = result.reason instanceof Error ? result.reason.message : String(result.reason);
-                    if (state && state.row.status !== 'failed') {
-                        await this.markStepFailed(state, error, runId);
-                    }
-                    batchOutcomes.push({
-                        name: step.name,
-                        agent: step.agent ?? 'deterministic',
-                        status: 'failed',
-                        attempts: (state?.row.retryCount ?? 0) + 1,
-                        error,
-                    });
-                    if (strategy === 'fail-fast') {
-                        // Mark all pending downstream steps as skipped
-                        await this.markDownstreamSkipped(step.name, workflow.steps, stepStates, runId);
-                        throw new Error(`Step "${step.name}" failed: ${error}`);
-                    }
-                    if (strategy === 'continue') {
-                        await this.markDownstreamSkipped(step.name, workflow.steps, stepStates, runId);
-                    }
-                }
-                else {
-                    batchOutcomes.push({
-                        name: step.name,
-                        agent: step.agent ?? 'deterministic',
-                        status: state?.row.status === 'completed' ? 'completed' : 'failed',
-                        attempts: (state?.row.retryCount ?? 0) + 1,
-                        output: state?.row.output,
-                        verificationPassed: state?.row.status === 'completed' && step.verification !== undefined,
-                        completionMode: state?.row.completionReason
-                            ? this.buildStepCompletionDecision(step.name, state.row.completionReason)?.mode
-                            : undefined,
-                    });
-                }
-            }
-            // Reflect at convergence when a parallel batch completes
-            if (readySteps.length > 1 && this.trajectory?.shouldReflectOnConverge()) {
-                const label = readySteps.map((s) => s.name).join(' + ');
-                // Find steps that this batch unblocks
-                const completedNames = new Set(batchOutcomes.filter((o) => o.status === 'completed').map((o) => o.name));
-                const unblocked = workflow.steps
-                    .filter((s) => s.dependsOn?.some((dep) => completedNames.has(dep)))
-                    .filter((s) => {
-                    const st = stepStates.get(s.name);
-                    return st && st.row.status === 'pending';
-                })
-                    .map((s) => s.name);
-                await this.trajectory.synthesizeAndReflect(label, batchOutcomes, unblocked.length > 0 ? unblocked : undefined);
-            }
-        }
+        const lifecycle = this.createStepLifecycleExecutor(workflow, stepStates, agentMap, errorHandling, runId);
+        await lifecycle.executeAll(workflow.steps, agentMap, {
+            ...(errorHandling ?? { strategy: 'fail-fast' }),
+            strategy,
+        }, stepStates);
     }
     findReadySteps(steps, stepStates) {
         return steps.filter((step) => {
@@ -2040,7 +2017,7 @@ export class WorkflowRunner {
                     const child = cpSpawn('sh', ['-c', check.command], {
                         stdio: 'pipe',
                         cwd: this.cwd,
-                        env: { ...process.env },
+                        env: filteredEnv(),
                     });
                     const stdoutChunks = [];
                     const stderrChunks = [];
@@ -2135,18 +2112,18 @@ export class WorkflowRunner {
     isIntegrationStep(step) {
         return step.type === 'integration';
     }
-    async executeStep(step, stepStates, agentMap, errorHandling, runId) {
+    async executeStep(step, state, stepStates, agentMap, errorHandling, runId, lifecycle) {
         // Branch: deterministic steps execute shell commands
         if (this.isDeterministicStep(step)) {
-            return this.executeDeterministicStep(step, stepStates, runId, errorHandling);
+            return this.executeDeterministicStep(step, state, stepStates, runId, errorHandling, lifecycle);
         }
         // Branch: worktree steps set up git worktrees
         if (this.isWorktreeStep(step)) {
-            return this.executeWorktreeStep(step, stepStates, runId);
+            return this.executeWorktreeStep(step, state, stepStates, runId, lifecycle);
         }
         // Branch: integration steps interact with external services
         if (this.isIntegrationStep(step)) {
-            return this.executeIntegrationStep(step, stepStates, runId);
+            return this.executeIntegrationStep(step, state, stepStates, runId, lifecycle);
         }
         // Agent step execution
         return this.executeAgentStep(step, stepStates, agentMap, errorHandling, runId);
@@ -2155,92 +2132,56 @@ export class WorkflowRunner {
      * Execute a deterministic step (shell command).
      * Fast, reliable, $0 LLM cost.
      */
-    async executeDeterministicStep(step, stepStates, runId, errorHandling) {
-        const state = stepStates.get(step.name);
-        if (!state)
-            throw new Error(`Step state not found: ${step.name}`);
+    async executeDeterministicStep(step, state, stepStates, runId, errorHandling, lifecycle) {
         const maxRetries = step.retries ?? errorHandling?.maxRetries ?? 0;
         const retryDelay = errorHandling?.retryDelayMs ?? 1000;
-        let lastError;
+        let lastError = 'Unknown error';
         let lastCompletionReason;
         let lastExitCode;
         let lastExitSignal;
-        for (let attempt = 0; attempt <= maxRetries; attempt += 1) {
-            this.checkAborted();
-            lastExitCode = undefined;
-            lastExitSignal = undefined;
-            if (attempt > 0) {
+        const result = await lifecycle.monitorStep(step, state, {
+            maxRetries,
+            retryDelayMs: retryDelay,
+            startMessage: `**[${step.name}]** Started (deterministic)`,
+            onRetry: async (attempt, total) => {
                 this.emit({ type: 'step:retrying', runId, stepName: step.name, attempt });
-                this.postToChannel(`**[${step.name}]** Retrying (attempt ${attempt + 1}/${maxRetries + 1})`);
+                this.postToChannel(`**[${step.name}]** Retrying (attempt ${attempt + 1}/${total + 1})`);
                 this.recordStepToolSideEffect(step.name, {
                     type: 'retry',
-                    detail: `Retrying attempt ${attempt + 1}/${maxRetries + 1}`,
-                    raw: { attempt, maxRetries },
+                    detail: `Retrying attempt ${attempt + 1}/${total + 1}`,
+                    raw: { attempt, maxRetries: total },
                 });
-                state.row.retryCount = attempt;
-                await this.db.updateStep(state.row.id, {
-                    retryCount: attempt,
-                    updatedAt: new Date().toISOString(),
+            },
+            execute: async () => {
+                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 !== undefined ? String(value) : _match;
                 });
-                await this.delay(retryDelay);
-            }
-            // Mark step as running
-            state.row.status = 'running';
-            state.row.error = undefined;
-            state.row.completionReason = undefined;
-            state.row.startedAt = new Date().toISOString();
-            await this.db.updateStep(state.row.id, {
-                status: 'running',
-                error: undefined,
-                completionReason: undefined,
-                startedAt: state.row.startedAt,
-                updatedAt: new Date().toISOString(),
-            });
-            this.emit({ type: 'step:started', runId, stepName: step.name });
-            this.postToChannel(`**[${step.name}]** Started (deterministic)`);
-            // Resolve variables in the command (e.g., {{steps.plan.output}}, {{branch-name}})
-            const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
-            let resolvedCommand = this.interpolateStepTask(step.command ?? '', stepOutputContext);
-            // Also resolve simple {{variable}} placeholders (already resolved in top-level config but safe to re-run)
-            resolvedCommand = resolvedCommand.replace(/\{\{([\w][\w.\-]*)\}\}/g, (_match, key) => {
-                if (key.startsWith('steps.'))
-                    return _match; // Already handled above
-                const value = this.resolveDotPath(key, stepOutputContext);
-                return value !== undefined ? String(value) : _match;
-            });
-            // Resolve step workdir (named path reference) for deterministic steps
-            const stepCwd = this.resolveEffectiveCwd(step);
-            this.beginStepEvidence(step.name, [stepCwd], state.row.startedAt);
-            try {
-                // Delegate to executor if present
+                const stepCwd = this.resolveEffectiveCwd(step);
+                this.beginStepEvidence(step.name, [stepCwd], state.row.startedAt);
                 if (this.executor?.executeDeterministicStep) {
-                    const result = await this.executor.executeDeterministicStep(step, resolvedCommand, stepCwd);
-                    lastExitCode = result.exitCode;
+                    const executorResult = await this.executor.executeDeterministicStep(step, resolvedCommand, stepCwd);
+                    lastExitCode = executorResult.exitCode;
+                    lastExitSignal = undefined;
                     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 (failOnError && executorResult.exitCode !== 0) {
+                        throw new Error(`Command failed with exit code ${executorResult.exitCode}: ${executorResult.output.slice(0, 500)}`);
                     }
-                    const output = step.captureOutput !== false ? result.output : `Command completed (exit code ${result.exitCode})`;
-                    this.captureStepTerminalEvidence(step.name, { stdout: result.output, combined: result.output }, { exitCode: result.exitCode });
+                    const output = step.captureOutput !== false
+                        ? executorResult.output
+                        : `Command completed (exit code ${executorResult.exitCode})`;
+                    this.captureStepTerminalEvidence(step.name, { stdout: executorResult.output, combined: executorResult.output }, { exitCode: executorResult.exitCode });
                     const verificationResult = step.verification
                         ? this.runVerification(step.verification, output, step.name)
                         : undefined;
-                    // Mark completed
-                    state.row.status = 'completed';
-                    state.row.output = output;
-                    state.row.completionReason = verificationResult?.completionReason;
-                    state.row.completedAt = new Date().toISOString();
-                    await this.db.updateStep(state.row.id, {
-                        status: 'completed',
+                    return {
                         output,
                         completionReason: verificationResult?.completionReason,
-                        completedAt: state.row.completedAt,
-                        updatedAt: new Date().toISOString(),
-                    });
-                    await this.persistStepOutput(runId, step.name, output);
-                    this.emit({ type: 'step:completed', runId, stepName: step.name, output });
-                    this.finalizeStepEvidence(step.name, 'completed', state.row.completedAt, verificationResult?.completionReason);
-                    return;
+                    };
                 }
                 let commandStdout = '';
                 let commandStderr = '';
@@ -2248,11 +2189,10 @@ export class WorkflowRunner {
                     const child = cpSpawn('sh', ['-c', resolvedCommand], {
                         stdio: 'pipe',
                         cwd: stepCwd,
-                        env: { ...process.env },
+                        env: filteredEnv(),
                     });
                     const stdoutChunks = [];
                     const stderrChunks = [];
-                    // Wire abort signal
                     const abortSignal = this.abortController?.signal;
                     let abortHandler;
                     if (abortSignal && !abortSignal.aborted) {
@@ -2262,7 +2202,6 @@ export class WorkflowRunner {
                         };
                         abortSignal.addEventListener('abort', abortHandler, { once: true });
                     }
-                    // Handle timeout
                     let timedOut = false;
                     let timer;
                     if (step.timeoutMs) {
@@ -2298,7 +2237,6 @@ export class WorkflowRunner {
                         commandStderr = stderr;
                         lastExitCode = code ?? undefined;
                         lastExitSignal = signal ?? undefined;
-                        // Check exit code unless failOnError is explicitly false
                         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)}` : ''}`));
@@ -2323,282 +2261,233 @@ export class WorkflowRunner {
                 const verificationResult = step.verification
                     ? this.runVerification(step.verification, output, step.name)
                     : undefined;
-                // Mark completed
-                state.row.status = 'completed';
-                state.row.output = output;
-                state.row.completionReason = verificationResult?.completionReason;
-                state.row.completedAt = new Date().toISOString();
-                await this.db.updateStep(state.row.id, {
-                    status: 'completed',
+                return {
                     output,
                     completionReason: verificationResult?.completionReason,
-                    completedAt: state.row.completedAt,
-                    updatedAt: new Date().toISOString(),
-                });
-                // Persist step output
-                await this.persistStepOutput(runId, step.name, output);
-                this.emit({ type: 'step:completed', runId, stepName: step.name, output });
-                this.finalizeStepEvidence(step.name, 'completed', state.row.completedAt, verificationResult?.completionReason);
-                return;
-            }
-            catch (err) {
-                lastError = err instanceof Error ? err.message : String(err);
-                lastCompletionReason =
-                    err instanceof WorkflowCompletionError ? err.completionReason : undefined;
-            }
+                };
+            },
+            toCompletionResult: ({ output, completionReason }, attempt) => ({
+                status: 'completed',
+                output,
+                completionReason,
+                retries: attempt,
+                exitCode: lastExitCode,
+                exitSignal: lastExitSignal,
+            }),
+            onAttemptFailed: async (error) => {
+                lastError = error instanceof Error ? error.message : String(error);
+                lastCompletionReason = error instanceof WorkflowCompletionError ? error.completionReason : undefined;
+            },
+            getFailureResult: () => ({
+                status: 'failed',
+                output: '',
+                error: lastError,
+                retries: state.row.retryCount,
+                exitCode: lastExitCode,
+                exitSignal: lastExitSignal,
+                completionReason: lastCompletionReason,
+            }),
+        });
+        if (result.status === 'failed') {
+            this.postToChannel(`**[${step.name}]** Failed: ${result.error ?? 'Unknown error'}`);
+            throw new Error(`Step "${step.name}" failed: ${result.error ?? 'Unknown error'}`);
         }
-        const errorMsg = lastError ?? 'Unknown error';
-        this.postToChannel(`**[${step.name}]** Failed: ${errorMsg}`);
-        await this.markStepFailed(state, errorMsg, runId, { exitCode: lastExitCode, exitSignal: lastExitSignal }, lastCompletionReason);
-        throw new Error(`Step "${step.name}" failed: ${errorMsg}`);
     }
     /**
      * Execute a worktree step (git worktree setup).
      * Fast, reliable, $0 LLM cost.
      * Outputs the worktree path for downstream steps to use.
      */
-    async executeWorktreeStep(step, stepStates, runId) {
-        const state = stepStates.get(step.name);
-        if (!state)
-            throw new Error(`Step state not found: ${step.name}`);
+    async executeWorktreeStep(step, state, stepStates, runId, lifecycle) {
         let lastExitCode;
         let lastExitSignal;
-        this.checkAborted();
-        // Mark step as running
-        state.row.status = 'running';
-        state.row.error = undefined;
-        state.row.completionReason = undefined;
-        state.row.startedAt = new Date().toISOString();
-        await this.db.updateStep(state.row.id, {
-            status: 'running',
-            error: undefined,
-            completionReason: undefined,
-            startedAt: state.row.startedAt,
-            updatedAt: new Date().toISOString(),
-        });
-        this.emit({ type: 'step:started', runId, stepName: step.name });
-        this.postToChannel(`**[${step.name}]** Started (worktree setup)`);
-        // Resolve variables in branch name and path
-        const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
-        const branch = this.interpolateStepTask(step.branch ?? '', stepOutputContext);
-        const baseBranch = step.baseBranch
-            ? this.interpolateStepTask(step.baseBranch, stepOutputContext)
-            : 'HEAD';
-        const worktreePath = step.path
-            ? this.interpolateStepTask(step.path, stepOutputContext)
-            : path.join('.worktrees', step.name);
-        const createBranch = step.createBranch !== false;
-        // Resolve workdir for worktree steps (same as deterministic/agent steps)
-        const stepCwd = this.resolveStepWorkdir(step) ?? this.cwd;
-        this.beginStepEvidence(step.name, [stepCwd], state.row.startedAt);
-        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 {
-            // Build the git worktree command
-            // If createBranch is true and branch doesn't exist, use -b flag
-            const absoluteWorktreePath = path.resolve(stepCwd, worktreePath);
-            // First, check if the branch already exists
-            const checkBranchCmd = `git rev-parse --verify --quiet ${branch} 2>/dev/null`;
-            let branchExists = false;
-            await new Promise((resolve) => {
-                const checkChild = cpSpawn('sh', ['-c', checkBranchCmd], {
-                    stdio: 'pipe',
-                    cwd: stepCwd,
-                    env: { ...process.env },
-                });
-                checkChild.on('close', (code) => {
-                    branchExists = code === 0;
-                    resolve();
-                });
-                checkChild.on('error', () => resolve());
-            });
-            // Build appropriate worktree add command
-            let worktreeCmd;
-            if (branchExists) {
-                // Branch exists, just checkout into worktree
-                worktreeCmd = `git worktree add "${absoluteWorktreePath}" ${branch}`;
-            }
-            else if (createBranch) {
-                // Create new branch from baseBranch
-                worktreeCmd = `git worktree add -b ${branch} "${absoluteWorktreePath}" ${baseBranch}`;
-            }
-            else {
-                // Branch doesn't exist and we're not creating it
-                const errorMsg = `Branch "${branch}" does not exist and createBranch is false`;
-                await this.markStepFailed(state, errorMsg, runId);
-                throw new Error(`Step "${step.name}" failed: ${errorMsg}`);
-            }
-            let commandStdout = '';
-            let commandStderr = '';
-            let commandExitCode;
-            let commandExitSignal;
-            const output = await new Promise((resolve, reject) => {
-                const child = cpSpawn('sh', ['-c', worktreeCmd], {
-                    stdio: 'pipe',
-                    cwd: stepCwd,
-                    env: { ...process.env },
+        let worktreeBranch = '';
+        let createdBranch = false;
+        const result = await lifecycle.monitorStep(step, state, {
+            startMessage: `**[${step.name}]** Started (worktree setup)`,
+            execute: async () => {
+                const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
+                const branch = this.interpolateStepTask(step.branch ?? '', stepOutputContext);
+                const baseBranch = step.baseBranch
+                    ? this.interpolateStepTask(step.baseBranch, stepOutputContext)
+                    : 'HEAD';
+                const worktreePath = step.path
+                    ? this.interpolateStepTask(step.path, stepOutputContext)
+                    : path.join('.worktrees', step.name);
+                const createBranch = step.createBranch !== false;
+                const stepCwd = this.resolveStepWorkdir(step) ?? this.cwd;
+                this.beginStepEvidence(step.name, [stepCwd], state.row.startedAt);
+                if (!branch) {
+                    throw new Error('Worktree step missing required "branch" field');
+                }
+                const absoluteWorktreePath = path.resolve(stepCwd, worktreePath);
+                let branchExists = false;
+                await new Promise((resolve) => {
+                    const checkChild = cpSpawn('git', ['rev-parse', '--verify', '--quiet', branch], {
+                        stdio: 'pipe',
+                        cwd: stepCwd,
+                        env: filteredEnv(),
+                    });
+                    checkChild.on('close', (code) => {
+                        branchExists = code === 0;
+                        resolve();
+                    });
+                    checkChild.on('error', () => resolve());
                 });
-                const stdoutChunks = [];
-                const stderrChunks = [];
-                // Wire abort signal
-                const abortSignal = this.abortController?.signal;
-                let abortHandler;
-                if (abortSignal && !abortSignal.aborted) {
-                    abortHandler = () => {
-                        child.kill('SIGTERM');
-                        setTimeout(() => child.kill('SIGKILL'), 5000);
-                    };
-                    abortSignal.addEventListener('abort', abortHandler, { once: true });
+                let worktreeArgs;
+                if (branchExists) {
+                    worktreeArgs = ['worktree', 'add', absoluteWorktreePath, branch];
                 }
-                // Handle timeout
-                let timedOut = false;
-                let timer;
-                if (step.timeoutMs) {
-                    timer = setTimeout(() => {
-                        timedOut = true;
-                        child.kill('SIGTERM');
-                        setTimeout(() => child.kill('SIGKILL'), 5000);
-                    }, step.timeoutMs);
+                else if (createBranch) {
+                    worktreeArgs = ['worktree', 'add', '-b', branch, absoluteWorktreePath, baseBranch];
                 }
-                child.stdout?.on('data', (chunk) => {
-                    stdoutChunks.push(chunk.toString());
-                });
-                child.stderr?.on('data', (chunk) => {
-                    stderrChunks.push(chunk.toString());
-                });
-                child.on('close', (code, signal) => {
-                    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;
-                    }
-                    commandStdout = stdoutChunks.join('');
-                    const stderr = stderrChunks.join('');
-                    commandStderr = stderr;
-                    commandExitCode = code ?? undefined;
-                    commandExitSignal = signal ?? undefined;
-                    lastExitCode = commandExitCode;
-                    lastExitSignal = commandExitSignal;
-                    if (code !== 0 && code !== null) {
-                        reject(new Error(`git worktree add failed with exit code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ''}`));
-                        return;
+                else {
+                    throw new Error(`Branch "${branch}" does not exist and createBranch is false`);
+                }
+                let commandStdout = '';
+                let commandStderr = '';
+                const output = await new Promise((resolve, reject) => {
+                    const child = cpSpawn('git', worktreeArgs, {
+                        stdio: 'pipe',
+                        cwd: stepCwd,
+                        env: filteredEnv(),
+                    });
+                    const stdoutChunks = [];
+                    const stderrChunks = [];
+                    const abortSignal = this.abortController?.signal;
+                    let abortHandler;
+                    if (abortSignal && !abortSignal.aborted) {
+                        abortHandler = () => {
+                            child.kill('SIGTERM');
+                            setTimeout(() => child.kill('SIGKILL'), 5000);
+                        };
+                        abortSignal.addEventListener('abort', abortHandler, { once: true });
                     }
-                    // Output the worktree path for downstream steps
-                    resolve(absoluteWorktreePath);
-                });
-                child.on('error', (err) => {
-                    if (timer)
-                        clearTimeout(timer);
-                    if (abortHandler && abortSignal) {
-                        abortSignal.removeEventListener('abort', abortHandler);
+                    let timedOut = false;
+                    let timer;
+                    if (step.timeoutMs) {
+                        timer = setTimeout(() => {
+                            timedOut = true;
+                            child.kill('SIGTERM');
+                            setTimeout(() => child.kill('SIGKILL'), 5000);
+                        }, step.timeoutMs);
                     }
-                    reject(new Error(`Failed to execute git worktree command: ${err.message}`));
+                    child.stdout?.on('data', (chunk) => {
+                        stdoutChunks.push(chunk.toString());
+                    });
+                    child.stderr?.on('data', (chunk) => {
+                        stderrChunks.push(chunk.toString());
+                    });
+                    child.on('close', (code, signal) => {
+                        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;
+                        }
+                        commandStdout = stdoutChunks.join('');
+                        commandStderr = stderrChunks.join('');
+                        lastExitCode = code ?? undefined;
+                        lastExitSignal = signal ?? undefined;
+                        if (code !== 0 && code !== null) {
+                            reject(new Error(`git worktree add failed with exit code ${code}${commandStderr ? `: ${commandStderr.slice(0, 500)}` : ''}`));
+                            return;
+                        }
+                        resolve(absoluteWorktreePath);
+                    });
+                    child.on('error', (err) => {
+                        if (timer)
+                            clearTimeout(timer);
+                        if (abortHandler && abortSignal) {
+                            abortSignal.removeEventListener('abort', abortHandler);
+                        }
+                        reject(new Error(`Failed to execute git worktree command: ${err.message}`));
+                    });
                 });
-            });
-            this.captureStepTerminalEvidence(step.name, {
-                stdout: commandStdout || output,
-                stderr: commandStderr,
-                combined: [commandStdout || output, commandStderr].filter(Boolean).join('\n'),
-            }, { exitCode: commandExitCode, exitSignal: commandExitSignal });
-            // Mark completed
-            state.row.status = 'completed';
-            state.row.output = output;
-            state.row.completedAt = new Date().toISOString();
-            await this.db.updateStep(state.row.id, {
+                this.captureStepTerminalEvidence(step.name, {
+                    stdout: commandStdout || output,
+                    stderr: commandStderr,
+                    combined: [commandStdout || output, commandStderr].filter(Boolean).join('\n'),
+                }, { exitCode: lastExitCode, exitSignal: lastExitSignal });
+                worktreeBranch = branch;
+                createdBranch = !branchExists && createBranch;
+                return { output };
+            },
+            toCompletionResult: ({ output }, attempt) => ({
                 status: 'completed',
                 output,
-                completedAt: state.row.completedAt,
-                updatedAt: new Date().toISOString(),
-            });
-            // Persist step output
-            await this.persistStepOutput(runId, step.name, output);
-            this.emit({ type: 'step:completed', runId, stepName: step.name, output });
-            this.postToChannel(`**[${step.name}]** Worktree created at: ${output}\n  Branch: ${branch}${!branchExists && createBranch ? ' (created)' : ''}`);
-            this.recordStepToolSideEffect(step.name, {
-                type: 'worktree_created',
-                detail: `Worktree created at ${output}`,
-                raw: { branch, createdBranch: !branchExists && createBranch },
-            });
-            this.finalizeStepEvidence(step.name, 'completed', state.row.completedAt);
-        }
-        catch (err) {
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            this.postToChannel(`**[${step.name}]** Failed: ${errorMsg}`);
-            await this.markStepFailed(state, errorMsg, runId, {
+                retries: attempt,
                 exitCode: lastExitCode,
                 exitSignal: lastExitSignal,
-            });
-            throw new Error(`Step "${step.name}" failed: ${errorMsg}`);
+            }),
+            getFailureResult: (error) => ({
+                status: 'failed',
+                output: '',
+                error: error instanceof Error ? error.message : String(error),
+                retries: state.row.retryCount,
+                exitCode: lastExitCode,
+                exitSignal: lastExitSignal,
+            }),
+        });
+        if (result.status === 'failed') {
+            this.postToChannel(`**[${step.name}]** Failed: ${result.error ?? 'Unknown error'}`);
+            throw new Error(`Step "${step.name}" failed: ${result.error ?? 'Unknown error'}`);
         }
+        this.postToChannel(`**[${step.name}]** Worktree created at: ${result.output}\n  Branch: ${worktreeBranch}${createdBranch ? ' (created)' : ''}`);
+        this.recordStepToolSideEffect(step.name, {
+            type: 'worktree_created',
+            detail: `Worktree created at ${result.output}`,
+            raw: { branch: worktreeBranch, createdBranch },
+        });
     }
     /**
      * Execute an integration step (external service interaction via executor).
      */
-    async executeIntegrationStep(step, stepStates, runId) {
-        const state = stepStates.get(step.name);
-        if (!state)
-            throw new Error(`Step state not found: ${step.name}`);
-        this.checkAborted();
-        // Mark step as running
-        state.row.status = 'running';
-        state.row.error = undefined;
-        state.row.completionReason = undefined;
-        state.row.startedAt = new Date().toISOString();
-        await this.db.updateStep(state.row.id, {
-            status: 'running',
-            error: undefined,
-            completionReason: undefined,
-            startedAt: state.row.startedAt,
-            updatedAt: new Date().toISOString(),
-        });
-        this.emit({ type: 'step:started', runId, stepName: step.name });
-        this.postToChannel(`**[${step.name}]** Started (integration: ${step.integration}.${step.action})`);
-        // Resolve {{steps.X.output}} in params
-        const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
-        const resolvedParams = {};
-        for (const [key, value] of Object.entries(step.params ?? {})) {
-            resolvedParams[key] = this.interpolateStepTask(value, stepOutputContext);
-        }
-        try {
-            if (!this.executor?.executeIntegrationStep) {
-                throw new Error(`Integration steps require a cloud executor. Step "${step.name}" cannot run locally. ` +
-                    `Use "cloud run" to execute workflows with integration steps.`);
-            }
-            const result = await this.executor.executeIntegrationStep(step, resolvedParams, { workspaceId: this.workspaceId });
-            if (!result.success) {
-                throw new Error(`Integration step "${step.name}" failed: ${result.output}`);
-            }
-            // Mark completed
-            state.row.status = 'completed';
-            state.row.output = result.output;
-            state.row.completedAt = new Date().toISOString();
-            await this.db.updateStep(state.row.id, {
+    async executeIntegrationStep(step, state, stepStates, runId, lifecycle) {
+        const result = await lifecycle.monitorStep(step, state, {
+            startMessage: `**[${step.name}]** Started (integration: ${step.integration}.${step.action})`,
+            execute: async () => {
+                const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
+                const resolvedParams = {};
+                for (const [key, value] of Object.entries(step.params ?? {})) {
+                    resolvedParams[key] = this.interpolateStepTask(value, stepOutputContext);
+                }
+                if (!this.executor?.executeIntegrationStep) {
+                    throw new Error(`Integration steps require a cloud executor. Step "${step.name}" cannot run locally. ` +
+                        `Use "cloud run" to execute workflows with integration steps.`);
+                }
+                const integrationResult = await this.executor.executeIntegrationStep(step, resolvedParams, {
+                    workspaceId: this.workspaceId,
+                });
+                if (!integrationResult.success) {
+                    throw new Error(`Integration step "${step.name}" failed: ${integrationResult.output}`);
+                }
+                return { output: integrationResult.output };
+            },
+            toCompletionResult: ({ output }, attempt) => ({
                 status: 'completed',
-                output: result.output,
-                completedAt: state.row.completedAt,
-                updatedAt: new Date().toISOString(),
-            });
-            await this.persistStepOutput(runId, step.name, result.output);
-            this.emit({ type: 'step:completed', runId, stepName: step.name, output: result.output });
-            this.postToChannel(`**[${step.name}]** Completed (integration: ${step.integration}.${step.action})`);
-        }
-        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}`);
+                output,
+                retries: attempt,
+            }),
+            getFailureResult: (error) => ({
+                status: 'failed',
+                output: '',
+                error: error instanceof Error ? error.message : String(error),
+                retries: state.row.retryCount,
+            }),
+        });
+        if (result.status === 'failed') {
+            this.postToChannel(`**[${step.name}]** Failed: ${result.error ?? 'Unknown error'}`);
+            throw new Error(`Step "${step.name}" failed: ${result.error ?? 'Unknown error'}`);
         }
+        this.postToChannel(`**[${step.name}]** Completed (integration: ${step.integration}.${step.action})`);
     }
     /**
      * Execute an agent step (LLM-powered).
@@ -2630,7 +2519,11 @@ export class WorkflowRunner {
             this.emit({ type: 'step:started', runId, stepName: step.name });
             this.postToChannel(`**[${step.name}]** Started (api)`);
             try {
-                const output = await executeApiStep(specialistDef.constraints?.model ?? 'claude-sonnet-4-20250514', resolvedTask, { envSecrets: this.envSecrets, skills: specialistDef.skills, defaultMaxTokens: specialistDef.constraints?.maxTokens });
+                const output = await executeApiStep(specialistDef.constraints?.model ?? 'claude-sonnet-4-20250514', resolvedTask, {
+                    envSecrets: this.envSecrets,
+                    skills: specialistDef.skills,
+                    defaultMaxTokens: specialistDef.constraints?.maxTokens,
+                });
                 state.row.status = 'completed';
                 state.row.output = output;
                 state.row.completedAt = new Date().toISOString();
@@ -2819,7 +2712,7 @@ export class WorkflowRunner {
                         : await this.spawnAndWait(effectiveOwner, resolvedStep, timeoutMs, {
                             evidenceStepName: step.name,
                             evidenceRole: usesOwnerFlow ? 'owner' : 'specialist',
-                            preserveOnIdle: (!isHubPattern || !this.isLeadLikeAgent(effectiveOwner)) ? false : undefined,
+                            preserveOnIdle: !isHubPattern || !this.isLeadLikeAgent(effectiveOwner) ? false : undefined,
                             logicalName: effectiveOwner.name,
                             onSpawned: explicitInteractiveWorker
                                 ? ({ agent }) => {
@@ -2843,7 +2736,7 @@ export class WorkflowRunner {
                             ? effectiveOwner.interactive === false
                                 ? undefined
                                 : ownerTask
-                            : spawnResult.promptTaskText ?? ownerTask;
+                            : (spawnResult.promptTaskText ?? ownerTask);
                     lastExitCode = typeof spawnResult === 'string' ? undefined : spawnResult.exitCode;
                     lastExitSignal = typeof spawnResult === 'string' ? undefined : spawnResult.exitSignal;
                     ownerElapsed = Date.now() - ownerStartTime;
@@ -2931,15 +2824,21 @@ export class WorkflowRunner {
                 });
                 // Persist step output to disk so it survives restarts and is inspectable
                 await this.persistStepOutput(runId, step.name, combinedOutput);
-                this.emit({ type: 'step:completed', runId, stepName: step.name, output: combinedOutput, exitCode: lastExitCode, exitSignal: lastExitSignal });
+                this.emit({
+                    type: 'step:completed',
+                    runId,
+                    stepName: step.name,
+                    output: combinedOutput,
+                    exitCode: lastExitCode,
+                    exitSignal: lastExitSignal,
+                });
                 this.finalizeStepEvidence(step.name, 'completed', state.row.completedAt, completionReason);
                 await this.trajectory?.stepCompleted(step, combinedOutput, attempt + 1);
                 return;
             }
             catch (err) {
                 lastError = err instanceof Error ? err.message : String(err);
-                lastCompletionReason =
-                    err instanceof WorkflowCompletionError ? err.completionReason : undefined;
+                lastCompletionReason = err instanceof WorkflowCompletionError ? err.completionReason : undefined;
                 if (lastCompletionReason === 'retry_requested_by_owner' && attempt >= maxRetries) {
                     lastError = this.buildOwnerRetryBudgetExceededMessage(step.name, maxRetries, lastError);
                 }
@@ -2979,9 +2878,7 @@ export class WorkflowRunner {
         const normalizedDecision = ownerDecisionError?.startsWith(prefix)
             ? ownerDecisionError.slice(prefix.length).trim()
             : ownerDecisionError?.trim();
-        const decisionSuffix = normalizedDecision
-            ? ` Latest owner decision: ${normalizedDecision}`
-            : '';
+        const decisionSuffix = normalizedDecision ? ` Latest owner decision: ${normalizedDecision}` : '';
         if (maxRetries === 0) {
             return (`Step "${stepName}" owner requested another attempt, but no retries are configured ` +
                 `(maxRetries=0). Configure retries > 0 to allow OWNER_DECISION: INCOMPLETE_RETRY.` +
@@ -3402,7 +3299,7 @@ export class WorkflowRunner {
     }
     hasOwnerCompletionMarker(step, output, injectedTaskText) {
         const marker = `STEP_COMPLETE:${step.name}`;
-        const strippedOutput = this.stripInjectedTaskEcho(output, injectedTaskText);
+        const strippedOutput = stripInjectedTaskEcho(output, injectedTaskText);
         if (strippedOutput.includes(marker)) {
             return true;
         }
@@ -3478,28 +3375,11 @@ export class WorkflowRunner {
             .filter((line) => patterns.every((pattern) => !pattern.test(line)))
             .join('\n');
     }
-    stripInjectedTaskEcho(output, injectedTaskText) {
-        if (!injectedTaskText) {
-            return output;
-        }
-        const candidates = [
-            injectedTaskText,
-            injectedTaskText.replace(/\r\n/g, '\n'),
-            injectedTaskText.replace(/\n/g, '\r\n'),
-        ].filter((candidate, index, all) => candidate.length > 0 && all.indexOf(candidate) === index);
-        for (const candidate of candidates) {
-            const start = output.indexOf(candidate);
-            if (start !== -1) {
-                return output.slice(0, start) + output.slice(start + candidate.length);
-            }
-        }
-        return output;
-    }
     outputContainsVerificationToken(output, token, injectedTaskText) {
         if (!token) {
             return false;
         }
-        return this.stripInjectedTaskEcho(output, injectedTaskText).includes(token);
+        return stripInjectedTaskEcho(output, injectedTaskText).includes(token);
     }
     prepareInteractiveSpawnTask(agentName, taskText) {
         if (Buffer.byteLength(taskText, 'utf8') <= WorkflowRunner.PTY_TASK_ARG_SIZE_LIMIT) {
@@ -3572,7 +3452,8 @@ export class WorkflowRunner {
         if (gracePeriodMs === 0)
             return null;
         // Never infer completion when the owner explicitly requested retry/fail/clarification.
-        if (ownerOutput && /OWNER_DECISION:\s*(?:INCOMPLETE_RETRY|INCOMPLETE_FAIL|NEEDS_CLARIFICATION)\b/i.test(ownerOutput)) {
+        if (ownerOutput &&
+            /OWNER_DECISION:\s*(?:INCOMPLETE_RETRY|INCOMPLETE_FAIL|NEEDS_CLARIFICATION)\b/i.test(ownerOutput)) {
             return null;
         }
         const evidence = this.getStepCompletionEvidence(step.name);
@@ -3860,17 +3741,10 @@ export class WorkflowRunner {
      * Delegates to the consolidated CLI registry for per-CLI arg formats.
      */
     static buildNonInteractiveCommand(cli, task, extraArgs = []) {
-        if (cli === 'api') {
-            throw new Error('cli "api" uses direct API calls, not a subprocess command');
-        }
-        const resolvedCli = cli === 'cursor' ? resolveCursorCli() : cli;
-        const def = getCliDefinition(resolvedCli);
-        if (!def || def.binaries.length === 0) {
-            throw new Error(`Unknown or non-executable CLI: ${resolvedCli}`);
-        }
+        const [cmd, ...args] = buildProcessCommand(cli, extraArgs, task);
         return {
-            cmd: def.binaries[0],
-            args: def.nonInteractiveArgs(task, extraArgs),
+            cmd,
+            args,
         };
     }
     /**
@@ -3966,11 +3840,11 @@ export class WorkflowRunner {
         const stdoutChunks = [];
         const stderrChunks = [];
         try {
-            const { stdout: output, exitCode, exitSignal } = await new Promise((resolve, reject) => {
-                const child = cpSpawn(cmd, args, {
+            const { stdout: output, exitCode, exitSignal, } = await new Promise((resolve, reject) => {
+                const child = spawnProcess([cmd, ...args], {
                     stdio: ['ignore', 'pipe', 'pipe'],
                     cwd: this.resolveEffectiveCwd(step, agentDef),
-                    env: this.getRelayEnv() ?? { ...process.env },
+                    env: this.getRelayEnv() ?? filteredEnv(),
                 });
                 // Update workers.json with PID now that we have it
                 this.registerWorker(agentName, agentDef.cli, step.task ?? '', child.pid, false);
@@ -4244,12 +4118,12 @@ export class WorkflowRunner {
                     if (verificationResult.passed) {
                         this.log(`[${step.name}] Agent timed out but verification passed — treating as complete`);
                         this.postToChannel(`**[${step.name}]** Agent idle after completing work — verification passed, releasing`);
-                        await agent.release();
+                        await agent.release().catch(() => undefined);
                         timeoutRecovered = true;
                     }
                 }
                 if (!timeoutRecovered) {
-                    await agent.release();
+                    await agent.release().catch(() => undefined);
                     throw new Error(`Step "${step.name}" timed out after ${timeoutMs ?? 'unknown'}ms`);
                 }
             }
@@ -4346,8 +4220,7 @@ export class WorkflowRunner {
             return true;
         const role = (roleOverride ?? agentDef.role ?? '').toLowerCase();
         const nameLC = agentDef.name.toLowerCase();
-        return [...WorkflowRunner.HUB_ROLES].some((hubRole) => new RegExp(`\\b${hubRole}\\b`, 'i').test(nameLC) ||
-            new RegExp(`\\b${hubRole}\\b`, 'i').test(role));
+        return [...WorkflowRunner.HUB_ROLES].some((hubRole) => new RegExp(`\\b${hubRole}\\b`, 'i').test(nameLC) || new RegExp(`\\b${hubRole}\\b`, 'i').test(role));
     }
     shouldPreserveIdleSupervisor(agentDef, step, evidenceRole) {
         if (evidenceRole && /\bowner\b/i.test(evidenceRole)) {
@@ -4411,13 +4284,13 @@ export class WorkflowRunner {
                             // Release and let upstream executeAgentStep handle verification.
                             this.log(`[${step.name}] Agent "${agent.name}" still idle after ${idleGraceSecs}s grace — releasing`);
                             this.postToChannel(`**[${step.name}]** Agent \`${agent.name}\` idle — releasing (verification pending)`);
-                            await agent.release();
+                            await agent.release().catch(() => undefined);
                             return 'released';
                         }
                     }
                     this.log(`[${step.name}] Agent "${agent.name}" went idle — treating as complete`);
                     this.postToChannel(`**[${step.name}]** Agent \`${agent.name}\` idle — treating as complete`);
-                    await agent.release();
+                    await agent.release().catch(() => undefined);
                     return 'released';
                 }
                 // Exit won the race, or idle returned 'exited'/'timeout' — pass through.
@@ -4474,7 +4347,7 @@ export class WorkflowRunner {
             // Exhausted nudges — force-release
             this.postToChannel(`**[${step.name}]** Agent \`${agent.name}\` still idle after ${nudgeCount} nudge(s) — force-releasing`);
             this.emit({ type: 'step:force-released', runId: this.currentRunId ?? '', stepName: step.name });
-            await agent.release();
+            await agent.release().catch(() => undefined);
             return 'force-released';
         }
     }
@@ -4541,74 +4414,11 @@ export class WorkflowRunner {
     }
     // ── Verification ────────────────────────────────────────────────────────
     runVerification(check, output, stepName, injectedTaskText, options) {
-        const fail = (message) => {
-            const observedAt = new Date().toISOString();
-            this.recordStepToolSideEffect(stepName, {
-                type: 'verification_observed',
-                detail: message,
-                observedAt,
-                raw: { passed: false, type: check.type, value: check.value },
-            });
-            this.getOrCreateStepEvidenceRecord(stepName).evidence.coordinationSignals.push({
-                kind: 'verification_failed',
-                source: 'verification',
-                text: message,
-                observedAt,
-                value: check.value,
-            });
-            if (options?.allowFailure) {
-                return {
-                    passed: false,
-                    completionReason: 'failed_verification',
-                    error: message,
-                };
-            }
-            throw new WorkflowCompletionError(message, 'failed_verification');
-        };
-        switch (check.type) {
-            case 'output_contains': {
-                const token = check.value;
-                if (!this.outputContainsVerificationToken(output, token, injectedTaskText)) {
-                    return fail(`Verification failed for "${stepName}": output does not contain "${token}"`);
-                }
-                break;
-            }
-            case 'exit_code':
-                // exit_code verification is implicitly satisfied if the agent exited successfully
-                break;
-            case 'file_exists':
-                if (!existsSync(path.resolve(this.cwd, check.value))) {
-                    return fail(`Verification failed for "${stepName}": file "${check.value}" does not exist`);
-                }
-                break;
-            case 'custom':
-                // Custom verifications are evaluated by callers; no-op here
-                return { passed: false };
-        }
-        if (options?.completionMarkerFound === false) {
-            this.log(`[${stepName}] Verification passed without legacy STEP_COMPLETE marker; allowing completion`);
-        }
-        const successMessage = options?.completionMarkerFound === false
-            ? `Verification passed without legacy STEP_COMPLETE marker`
-            : `Verification passed`;
-        const observedAt = new Date().toISOString();
-        this.recordStepToolSideEffect(stepName, {
-            type: 'verification_observed',
-            detail: successMessage,
-            observedAt,
-            raw: { passed: true, type: check.type, value: check.value },
-        });
-        this.getOrCreateStepEvidenceRecord(stepName).evidence.coordinationSignals.push({
-            kind: 'verification_passed',
-            source: 'verification',
-            text: successMessage,
-            observedAt,
-            value: check.value,
+        return runVerification(check, output, stepName, injectedTaskText, { ...options, cwd: this.cwd }, {
+            recordStepToolSideEffect: (name, effect) => this.recordStepToolSideEffect(name, effect),
+            getOrCreateStepEvidenceRecord: (name) => this.getOrCreateStepEvidenceRecord(name),
+            log: (message) => this.log(message),
         });
-        return {
-            passed: true,
-            completionReason: 'completed_verified',
-        };
     }
     // ── State helpers ─────────────────────────────────────────────────────
     async updateRunStatus(runId, status, error) {
@@ -4743,29 +4553,7 @@ export class WorkflowRunner {
      * Returns undefined if there are no non-interactive agents.
      */
     buildNonInteractiveAwareness(agentMap, stepStates) {
-        const nonInteractive = [...agentMap.values()].filter((a) => a.interactive === false);
-        if (nonInteractive.length === 0)
-            return undefined;
-        // Map agent names to their step names so the lead knows exact {{steps.X.output}} references
-        const agentToSteps = new Map();
-        for (const [stepName, state] of stepStates) {
-            const agentName = state.row.agentName;
-            if (!agentName)
-                continue; // Skip deterministic steps
-            if (!agentToSteps.has(agentName))
-                agentToSteps.set(agentName, []);
-            agentToSteps.get(agentName).push(stepName);
-        }
-        const lines = nonInteractive.map((a) => {
-            const steps = agentToSteps.get(a.name) ?? [];
-            const stepRefs = steps.map((s) => `{{steps.${s}.output}}`).join(', ');
-            return `- ${a.name} (${a.cli}) — will return output when complete${stepRefs ? `. Access via: ${stepRefs}` : ''}`;
-        });
-        return ('\n\n---\n' +
-            'Note: The following agents are non-interactive workers and cannot receive messages:\n' +
-            lines.join('\n') +
-            '\n' +
-            'Do NOT attempt to message these agents. Use the {{steps.<name>.output}} references above to access their results.');
+        return this.channelMessenger.buildNonInteractiveAwareness(agentMap, stepStates);
     }
     /**
      * Build guidance that encourages agents to autonomously delegate subtasks
@@ -4780,46 +4568,10 @@ export class WorkflowRunner {
      * key, but they won't call `register` unless explicitly told to.
      */
     buildRelayRegistrationNote(cli, agentName) {
-        if (cli === 'claude')
-            return '';
-        return ('---\n' +
-            'RELAY SETUP — do this FIRST before any other relay tool:\n' +
-            `1. Call: register(name="${agentName}")\n` +
-            '   This authenticates you in the Relaycast workspace.\n' +
-            '   ALL relay tools (mcp__relaycast__message_dm_send, mcp__relaycast__message_inbox_check, mcp__relaycast__message_post, etc.) require\n' +
-            '   registration first — they will fail with "Not registered" otherwise.\n' +
-            `2. Your agent name is "${agentName}" — use this exact name when registering.`);
+        return this.channelMessenger.buildRelayRegistrationNote(cli, agentName);
     }
     buildDelegationGuidance(cli, timeoutMs) {
-        const timeoutNote = timeoutMs
-            ? `You have approximately ${Math.round(timeoutMs / 60000)} minutes before this step times out. ` +
-                'Plan accordingly — delegate early if the work is substantial.\n\n'
-            : '';
-        // Option 2 (sub-agents via Task tool) is only available in Claude
-        const subAgentOption = cli === 'claude'
-            ? 'Option 2 — Use built-in sub-agents (Task tool) for research or scoped work:\n' +
-                '  - Good for exploring code, reading files, or making targeted changes\n' +
-                '  - Can run multiple sub-agents in parallel\n\n'
-            : '';
-        return ('---\n' +
-            'AUTONOMOUS DELEGATION — READ THIS BEFORE STARTING:\n' +
-            timeoutNote +
-            'Before diving in, assess whether this task is too large or complex for a single agent. ' +
-            'If it involves multiple independent subtasks, touches many files, or could take a long time, ' +
-            'you should break it down and delegate to helper agents to avoid timeouts.\n\n' +
-            'Option 1 — Spawn relay agents (for real parallel coding work):\n' +
-            '  - mcp__relaycast__agent_add(name="helper-1", cli="claude", task="Specific subtask description")\n' +
-            '  - Coordinate via mcp__relaycast__message_dm_send(to="helper-1", text="...")\n' +
-            '  - Check on them with mcp__relaycast__message_inbox_check()\n' +
-            '  - Clean up when done: mcp__relaycast__agent_remove(name="helper-1")\n\n' +
-            subAgentOption +
-            'Guidelines:\n' +
-            '- You are the lead — delegate but stay in control, track progress, integrate results\n' +
-            '- Give each helper a clear, self-contained task with enough context to work independently\n' +
-            "- For simple or quick work, just do it yourself — don't over-delegate\n" +
-            '- Always release spawned relay agents when their work is complete\n' +
-            '- When spawning non-claude agents (codex, gemini, etc.), prepend to their task:\n' +
-            '  "RELAY SETUP: First call register(name=\'<exact-agent-name>\') before any other relay tool."');
+        return this.channelMessenger.buildDelegationGuidance(cli, timeoutMs);
     }
     /** Post a message to the workflow channel. Fire-and-forget — never throws or blocks. */
     postToChannel(text, options = {}) {
@@ -4847,43 +4599,11 @@ export class WorkflowRunner {
     }
     /** Post a rich completion report to the channel. */
     postCompletionReport(workflowName, outcomes, summary, confidence) {
-        const completed = outcomes.filter((o) => o.status === 'completed');
-        const skipped = outcomes.filter((o) => o.status === 'skipped');
-        const retried = outcomes.filter((o) => o.attempts > 1);
-        const lines = [
-            `## Workflow **${workflowName}** — Complete`,
-            '',
-            summary,
-            `Confidence: ${Math.round(confidence * 100)}%`,
-            '',
-            '### Steps',
-            ...completed.map((o) => `- **${o.name}** (${o.agent}) — passed${o.verificationPassed ? ' (verified)' : ''}${o.attempts > 1 ? ` after ${o.attempts} attempts` : ''}`),
-            ...skipped.map((o) => `- **${o.name}** — skipped`),
-        ];
-        if (retried.length > 0) {
-            lines.push('', '### Retries');
-            for (const o of retried) {
-                lines.push(`- ${o.name}: ${o.attempts} attempts`);
-            }
-        }
-        this.postToChannel(lines.join('\n'));
+        this.channelMessenger.postCompletionReport(workflowName, outcomes, summary, confidence);
     }
     /** Post a failure report to the channel. */
     postFailureReport(workflowName, outcomes, errorMsg) {
-        const completed = outcomes.filter((o) => o.status === 'completed');
-        const failed = outcomes.filter((o) => o.status === 'failed');
-        const skipped = outcomes.filter((o) => o.status === 'skipped');
-        const lines = [
-            `## Workflow **${workflowName}** — Failed`,
-            '',
-            `${completed.length}/${outcomes.length} steps passed. Error: ${errorMsg}`,
-            '',
-            '### Steps',
-            ...completed.map((o) => `- **${o.name}** (${o.agent}) — passed`),
-            ...failed.map((o) => `- **${o.name}** (${o.agent}) — FAILED: ${o.error ?? 'unknown'}`),
-            ...skipped.map((o) => `- **${o.name}** — skipped`),
-        ];
-        this.postToChannel(lines.join('\n'));
+        this.channelMessenger.postFailureReport(workflowName, outcomes, errorMsg);
     }
     /**
      * Log a human-readable run summary to the console after completion or failure.
@@ -5209,7 +4929,7 @@ export class WorkflowRunner {
                     if (!stat.isDirectory())
                         continue;
                     // Check if this directory has at least one of the needed step files
-                    const hasAny = [...stepNames].some(name => existsSync(path.join(dirPath, `${name}.md`)));
+                    const hasAny = [...stepNames].some((name) => existsSync(path.join(dirPath, `${name}.md`)));
                     if (!hasAny)
                         continue;
                     if (!best || stat.mtimeMs > best.mtime) {
@@ -5338,7 +5058,11 @@ export class WorkflowRunner {
         for (const step of workflow.steps) {
             const isNonAgent = step.type === 'deterministic' || step.type === 'worktree' || step.type === 'integration';
             const cachedOutput = completedSteps.has(step.name) ? this.loadStepOutput(runId, step.name) : undefined;
-            const status = completedSteps.has(step.name) ? 'completed' : step.name === failedStepName ? 'failed' : 'pending';
+            const status = completedSteps.has(step.name)
+                ? 'completed'
+                : step.name === failedStepName
+                    ? 'failed'
+                    : 'pending';
             const stepRow = {
                 id: this.generateId(),
                 runId,
@@ -5351,7 +5075,7 @@ export class WorkflowRunner {
                     : step.type === 'worktree'
                         ? (step.branch ?? '')
                         : step.type === 'integration'
-                            ? (`${step.integration}.${step.action}`)
+                            ? `${step.integration}.${step.action}`
                             : (step.task ?? ''),
                 dependsOn: step.dependsOn ?? [],
                 output: cachedOutput,