agent-relay 2.3.14 → 2.3.16

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

@@ -0,0 +1,2821 @@
+/**
+ * WorkflowRunner — parses relay.yaml, validates config, resolves templates,
+ * executes steps (sequential/parallel/DAG), runs verification checks,
+ * persists state to DB, and supports pause/resume/abort with retries.
+ */
+import { spawn as cpSpawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { stripAnsi as stripAnsiFn } from '../pty.js';
+import { loadCustomSteps, resolveAllCustomSteps, validateCustomStepsUsage, CustomStepsParseError, CustomStepResolutionError, } from './custom-steps.js';
+import { InMemoryWorkflowDb } from './memory-db.js';
+import { WorkflowTrajectory } from './trajectory.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';
+// ── WorkflowRunner ──────────────────────────────────────────────────────────
+export class WorkflowRunner {
+    db;
+    workspaceId;
+    relayOptions;
+    cwd;
+    summaryDir;
+    /** @internal exposed for CLI signal-handler shutdown only */
+    relay;
+    relaycast;
+    relaycastAgent;
+    relayApiKey;
+    relayApiKeyAutoCreated = false;
+    channel;
+    trajectory;
+    abortController;
+    paused = false;
+    pauseResolver;
+    listeners = [];
+    /** Current config for the active run, so spawnAndWait can access swarm config. */
+    currentConfig;
+    /** Current run ID for event emission from spawnAndWait context. */
+    currentRunId;
+    /** Live Agent handles keyed by name, for hub-mediated nudging. */
+    activeAgentHandles = new Map();
+    // PTY-based output capture: accumulate terminal output per-agent
+    ptyOutputBuffers = new Map();
+    ptyListeners = new Map();
+    ptyLogStreams = new Map();
+    /** Path to workers.json so `agents:kill` can find workflow-spawned agents */
+    workersPath;
+    /** In-memory tracking of active workers to avoid race conditions on workers.json */
+    activeWorkers = new Map();
+    /** Mutex for serializing workers.json file access */
+    workersFileLock = Promise.resolve();
+    /** Timestamp when the current workflow run started, for elapsed-time logging. */
+    runStartTime;
+    /** Unsubscribe handle for broker stderr listener wired during a run. */
+    unsubBrokerStderr;
+    /** Tracks last idle log time per agent to debounce idle warnings (30s multiples). */
+    lastIdleLog = new Map();
+    /** Tracks last logged activity type per agent to avoid duplicate status lines. */
+    lastActivity = new Map();
+    constructor(options = {}) {
+        this.db = options.db ?? new InMemoryWorkflowDb();
+        this.workspaceId = options.workspaceId ?? 'local';
+        this.relayOptions = options.relay ?? {};
+        this.cwd = options.cwd ?? process.cwd();
+        this.summaryDir = options.summaryDir ?? path.join(this.cwd, '.relay', 'summaries');
+        this.workersPath = path.join(this.cwd, '.agent-relay', 'team', 'workers.json');
+    }
+    // ── Progress logging ────────────────────────────────────────────────────
+    /** Log a progress message with elapsed time since run start. */
+    log(msg) {
+        const elapsed = this.runStartTime ? Math.round((Date.now() - this.runStartTime) / 1000) : 0;
+        const mins = Math.floor(elapsed / 60);
+        const secs = elapsed % 60;
+        const ts = mins > 0
+            ? `${String(mins).padStart(2, '0')}:${String(secs).padStart(2, '0')}`
+            : `00:${String(secs).padStart(2, '0')}`;
+        console.log(`[workflow ${ts}] ${msg}`);
+    }
+    // ── Relaycast auto-provisioning ────────────────────────────────────────
+    /**
+     * Ensure a Relaycast workspace API key is available for the broker.
+     * Resolution order:
+     *   1. RELAY_API_KEY environment variable (explicit override)
+     *   2. Auto-create a fresh workspace via the Relaycast API
+     *
+     * Each workflow run gets its own isolated workspace — no caching, no sharing.
+     */
+    async ensureRelaycastApiKey(channel) {
+        if (this.relayApiKey)
+            return;
+        // Explicit override from relayOptions or environment takes priority.
+        const envKey = this.relayOptions.env?.RELAY_API_KEY ?? process.env.RELAY_API_KEY;
+        if (envKey) {
+            this.relayApiKey = envKey;
+            return;
+        }
+        // Always create a fresh workspace — each run gets full isolation.
+        const workspaceName = `relay-${channel}-${randomBytes(4).toString('hex')}`;
+        const baseUrl = this.relayOptions.env?.RELAYCAST_BASE_URL ??
+            process.env.RELAYCAST_BASE_URL ??
+            'https://api.relaycast.dev';
+        const res = await fetch(`${baseUrl}/v1/workspaces`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ name: workspaceName }),
+        });
+        if (!res.ok) {
+            throw new Error(`Failed to auto-create Relaycast workspace: ${res.status} ${await res.text()}`);
+        }
+        const body = (await res.json());
+        const data = (body.data ?? body);
+        const apiKey = data.api_key;
+        if (!apiKey) {
+            throw new Error('Relaycast workspace response missing api_key');
+        }
+        this.relayApiKey = apiKey;
+        this.relayApiKeyAutoCreated = true;
+    }
+    getRelayEnv() {
+        if (!this.relayApiKey) {
+            return this.relayOptions.env;
+        }
+        return {
+            ...(this.relayOptions.env ?? process.env),
+            RELAY_API_KEY: this.relayApiKey,
+        };
+    }
+    getRelaycastBaseUrl() {
+        return (this.relayOptions.env?.RELAYCAST_BASE_URL ??
+            process.env.RELAYCAST_BASE_URL ??
+            'https://api.relaycast.dev');
+    }
+    getRelaycastClient() {
+        if (!this.relayApiKey) {
+            throw new Error('No Relaycast API key available');
+        }
+        if (!this.relaycast) {
+            this.relaycast = new RelayCast({
+                apiKey: this.relayApiKey,
+                baseUrl: this.getRelaycastBaseUrl(),
+            });
+        }
+        return this.relaycast;
+    }
+    async ensureRelaycastRunnerAgent() {
+        if (this.relaycastAgent)
+            return this.relaycastAgent;
+        const rc = this.getRelaycastClient();
+        let registration;
+        try {
+            registration = await rc.agents.register({ name: 'WorkflowRunner', type: 'agent' });
+        }
+        catch (err) {
+            if (err instanceof RelayError && err.code === 'name_conflict') {
+                registration = await rc.agents.register({
+                    name: `WorkflowRunner-${randomBytes(4).toString('hex')}`,
+                    type: 'agent',
+                });
+            }
+            else {
+                throw err;
+            }
+        }
+        this.relaycastAgent = rc.as(registration.token);
+        return this.relaycastAgent;
+    }
+    async createAndJoinRelaycastChannel(channel, topic) {
+        const agent = await this.ensureRelaycastRunnerAgent();
+        try {
+            await agent.channels.create({ name: channel, ...(topic ? { topic } : {}) });
+        }
+        catch (err) {
+            if (!(err instanceof RelayError && err.code === 'name_conflict')) {
+                throw err;
+            }
+        }
+        await agent.channels.join(channel);
+    }
+    async registerRelaycastExternalAgent(name, persona) {
+        const rc = this.getRelaycastClient();
+        try {
+            const registration = await rc.agents.register({
+                name,
+                type: 'agent',
+                ...(persona ? { persona } : {}),
+            });
+            return rc.as(registration.token);
+        }
+        catch (err) {
+            if (err instanceof RelayError && err.code === 'name_conflict') {
+                return null;
+            }
+            throw err;
+        }
+    }
+    startRelaycastHeartbeat(agent, intervalMs = 30_000) {
+        const beat = () => {
+            agent.heartbeat().catch(() => { });
+        };
+        const timer = setInterval(beat, intervalMs);
+        timer.unref();
+        beat();
+        return () => clearInterval(timer);
+    }
+    // ── Event subscription ──────────────────────────────────────────────────
+    on(listener) {
+        this.listeners.push(listener);
+        return () => {
+            this.listeners = this.listeners.filter((l) => l !== listener);
+        };
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            listener(event);
+        }
+    }
+    // ── Parsing & validation ────────────────────────────────────────────────
+    /** Parse a relay.yaml file from disk. */
+    async parseYamlFile(filePath) {
+        const absPath = path.resolve(this.cwd, filePath);
+        const raw = await readFile(absPath, 'utf-8');
+        return this.parseYamlString(raw, absPath);
+    }
+    /** Parse a relay.yaml string. */
+    parseYamlString(raw, source = '<string>') {
+        const parsed = parseYaml(raw);
+        this.validateConfig(parsed, source);
+        const config = parsed;
+        config.agents ??= [];
+        return config;
+    }
+    /** Validate a config object against the RelayYamlConfig shape. */
+    validateConfig(config, source = '<config>') {
+        if (typeof config !== 'object' || config === null) {
+            throw new Error(`${source}: config must be a non-null object`);
+        }
+        const c = config;
+        if (typeof c.version !== 'string') {
+            throw new Error(`${source}: missing required field "version"`);
+        }
+        if (typeof c.name !== 'string') {
+            throw new Error(`${source}: missing required field "name"`);
+        }
+        if (typeof c.swarm !== 'object' || c.swarm === null) {
+            throw new Error(`${source}: missing required field "swarm"`);
+        }
+        const swarm = c.swarm;
+        if (typeof swarm.pattern !== 'string') {
+            throw new Error(`${source}: missing required field "swarm.pattern"`);
+        }
+        if (c.agents !== undefined && !Array.isArray(c.agents)) {
+            throw new Error(`${source}: "agents" must be an array when provided`);
+        }
+        for (const agent of c.agents ?? []) {
+            if (typeof agent !== 'object' || agent === null) {
+                throw new Error(`${source}: each agent must be an object`);
+            }
+            const a = agent;
+            if (typeof a.name !== 'string') {
+                throw new Error(`${source}: each agent must have a string "name"`);
+            }
+            if (typeof a.cli !== 'string') {
+                throw new Error(`${source}: each agent must have a string "cli"`);
+            }
+        }
+        if (c.workflows !== undefined) {
+            if (!Array.isArray(c.workflows)) {
+                throw new Error(`${source}: "workflows" must be an array`);
+            }
+            for (const wf of c.workflows) {
+                this.validateWorkflow(wf, (c.agents ?? []), source);
+            }
+        }
+    }
+    // ── Dry-run simulation ──────────────────────────────────────────────
+    /**
+     * Validate a workflow config and simulate execution waves without spawning agents.
+     * Returns a DryRunReport with DAG analysis, agent summary, and wave breakdown.
+     */
+    dryRun(config, workflowName, vars) {
+        const errors = [];
+        const warnings = [];
+        // 1. Validate config
+        let resolved;
+        try {
+            this.validateConfig(config);
+            resolved = vars ? this.resolveVariables(config, vars) : config;
+        }
+        catch (err) {
+            errors.push(err instanceof Error ? err.message : String(err));
+            return {
+                valid: false,
+                errors,
+                warnings,
+                name: config?.name ?? '<unknown>',
+                pattern: config?.swarm?.pattern ?? '<unknown>',
+                agents: [],
+                waves: [],
+                totalSteps: 0,
+                estimatedWaves: 0,
+            };
+        }
+        // 2. Find target workflow
+        const workflows = resolved.workflows ?? [];
+        const workflow = workflowName ? workflows.find((w) => w.name === workflowName) : workflows[0];
+        if (!workflow) {
+            errors.push(workflowName ? `Workflow "${workflowName}" not found in config` : 'No workflows defined in config');
+            return {
+                valid: false,
+                errors,
+                warnings,
+                name: resolved.name,
+                description: resolved.description,
+                pattern: resolved.swarm.pattern,
+                agents: [],
+                waves: [],
+                totalSteps: 0,
+                estimatedWaves: 0,
+            };
+        }
+        // 3. Load and validate custom steps
+        let customSteps = new Map();
+        try {
+            customSteps = loadCustomSteps(this.cwd);
+        }
+        catch (err) {
+            if (err instanceof CustomStepsParseError) {
+                errors.push(`Custom steps file error: ${err.issue}\n${err.suggestion}`);
+            }
+            else {
+                errors.push(`Failed to load custom steps: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        // Validate custom step usage in workflow steps
+        const customStepValidation = validateCustomStepsUsage(workflow.steps, customSteps);
+        errors.push(...customStepValidation.errors);
+        warnings.push(...customStepValidation.warnings);
+        // Resolve custom steps for further validation
+        let resolvedSteps = workflow.steps;
+        if (customStepValidation.valid) {
+            try {
+                resolvedSteps = resolveAllCustomSteps(workflow.steps, customSteps);
+            }
+            catch (err) {
+                if (err instanceof CustomStepResolutionError) {
+                    errors.push(`${err.issue}\n${err.suggestion}`);
+                }
+                else {
+                    errors.push(`Failed to resolve custom steps: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        // 4. Build agent map and validate step→agent references
+        const agentMap = new Map();
+        for (const agent of resolved.agents) {
+            agentMap.set(agent.name, agent);
+        }
+        const stepAgentCounts = new Map();
+        for (const step of resolvedSteps) {
+            // Only validate agent references for agent-type steps
+            if (step.agent) {
+                if (!agentMap.has(step.agent)) {
+                    warnings.push(`Step "${step.name}" references unknown agent "${step.agent}"`);
+                }
+                stepAgentCounts.set(step.agent, (stepAgentCounts.get(step.agent) ?? 0) + 1);
+            }
+        }
+        // Validate cwd paths
+        for (const agent of resolved.agents) {
+            if (agent.cwd) {
+                const resolvedCwd = path.resolve(this.cwd, agent.cwd);
+                if (!existsSync(resolvedCwd)) {
+                    warnings.push(`Agent "${agent.name}" cwd "${agent.cwd}" resolves to "${resolvedCwd}" which does not exist`);
+                }
+            }
+            if (agent.additionalPaths) {
+                for (const ap of agent.additionalPaths) {
+                    const resolvedPath = path.resolve(this.cwd, ap);
+                    if (!existsSync(resolvedPath)) {
+                        warnings.push(`Agent "${agent.name}" additionalPath "${ap}" resolves to "${resolvedPath}" which does not exist`);
+                    }
+                }
+            }
+        }
+        // Cycle detection via topological sort
+        const stepNames = new Set(resolvedSteps.map((s) => s.name));
+        const inDegree = new Map();
+        const adjacency = new Map();
+        for (const step of resolvedSteps) {
+            inDegree.set(step.name, 0);
+            adjacency.set(step.name, []);
+        }
+        for (const step of resolvedSteps) {
+            for (const dep of step.dependsOn ?? []) {
+                if (stepNames.has(dep)) {
+                    adjacency.get(dep).push(step.name);
+                    inDegree.set(step.name, (inDegree.get(step.name) ?? 0) + 1);
+                }
+            }
+        }
+        const topoQueue = [];
+        for (const [name, deg] of inDegree) {
+            if (deg === 0)
+                topoQueue.push(name);
+        }
+        let visited = 0;
+        while (topoQueue.length > 0) {
+            const node = topoQueue.shift();
+            visited++;
+            for (const neighbor of adjacency.get(node) ?? []) {
+                const newDeg = (inDegree.get(neighbor) ?? 1) - 1;
+                inDegree.set(neighbor, newDeg);
+                if (newDeg === 0)
+                    topoQueue.push(neighbor);
+            }
+        }
+        if (visited < resolvedSteps.length) {
+            errors.push('Dependency cycle detected in workflow steps. Check dependsOn references for circular dependencies.');
+        }
+        // Missing dependency references
+        for (const step of resolvedSteps) {
+            for (const dep of step.dependsOn ?? []) {
+                if (!stepNames.has(dep)) {
+                    errors.push(`Step "${step.name}" depends on unknown step "${dep}"`);
+                }
+            }
+        }
+        // Unreachable steps (steps that are never depended on and aren't root steps)
+        const dependedOn = new Set();
+        for (const step of resolvedSteps) {
+            for (const dep of step.dependsOn ?? []) {
+                dependedOn.add(dep);
+            }
+        }
+        // Timeout warnings
+        for (const step of resolvedSteps) {
+            if (!step.timeoutMs) {
+                const agentDef = step.agent ? agentMap.get(step.agent) : undefined;
+                if (!agentDef?.constraints?.timeoutMs && !resolved.swarm.timeoutMs) {
+                    warnings.push(`Step "${step.name}" has no timeout configured (no step, agent, or swarm-level timeout)`);
+                }
+            }
+        }
+        // Large dependency fan-in warning (decomposition guidance)
+        for (const step of resolvedSteps) {
+            if ((step.dependsOn?.length ?? 0) >= 5) {
+                warnings.push(`Step "${step.name}" depends on ${step.dependsOn.length} upstream steps. ` +
+                    `Consider decomposing into smaller verification steps to reduce context size.`);
+            }
+        }
+        // 4. Build agent summary
+        const agents = resolved.agents.map((a) => ({
+            name: a.name,
+            cli: a.cli,
+            role: a.role,
+            cwd: a.cwd,
+            stepCount: stepAgentCounts.get(a.name) ?? 0,
+        }));
+        // 5. Simulate execution waves
+        const waves = [];
+        const completed = new Set();
+        const allSteps = [...resolvedSteps];
+        let waveNum = 0;
+        while (completed.size < allSteps.length) {
+            const ready = allSteps.filter((step) => {
+                if (completed.has(step.name))
+                    return false;
+                const deps = step.dependsOn ?? [];
+                return deps.every((dep) => completed.has(dep));
+            });
+            if (ready.length === 0) {
+                // Remaining steps are blocked — likely a cycle or unresolvable deps
+                const blocked = allSteps.filter((s) => !completed.has(s.name)).map((s) => s.name);
+                errors.push(`Blocked steps with unresolvable dependencies: ${blocked.join(', ')}`);
+                break;
+            }
+            waveNum++;
+            waves.push({
+                wave: waveNum,
+                steps: ready.map((s) => ({
+                    name: s.name,
+                    agent: s.agent,
+                    dependsOn: s.dependsOn ?? [],
+                })),
+            });
+            for (const step of ready) {
+                completed.add(step.name);
+            }
+        }
+        // 6. Resource estimation
+        const peakConcurrency = Math.max(...waves.map((w) => w.steps.length), 0);
+        const totalAgentSteps = resolvedSteps.filter((s) => s.type !== 'deterministic' && s.type !== 'worktree').length;
+        // 7. Check maxConcurrency against wave widths
+        const maxConcurrency = resolved.swarm.maxConcurrency;
+        if (maxConcurrency !== undefined) {
+            for (const wave of waves) {
+                if (wave.steps.length > maxConcurrency) {
+                    warnings.push(`Wave ${wave.wave} has ${wave.steps.length} parallel steps but maxConcurrency is ${maxConcurrency}`);
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors,
+            warnings,
+            name: workflow.name,
+            description: workflow.description ?? resolved.description,
+            pattern: resolved.swarm.pattern,
+            agents,
+            waves,
+            totalSteps: workflow.steps.length,
+            maxConcurrency,
+            estimatedWaves: waves.length,
+            estimatedPeakConcurrency: peakConcurrency,
+            estimatedTotalAgentSteps: totalAgentSteps,
+        };
+    }
+    validateWorkflow(wf, agents, source) {
+        if (typeof wf !== 'object' || wf === null) {
+            throw new Error(`${source}: each workflow must be an object`);
+        }
+        const w = wf;
+        if (typeof w.name !== 'string') {
+            throw new Error(`${source}: each workflow must have a string "name"`);
+        }
+        if (!Array.isArray(w.steps) || w.steps.length === 0) {
+            throw new Error(`${source}: workflow "${w.name}" must have a non-empty "steps" array`);
+        }
+        for (const step of w.steps) {
+            if (typeof step !== 'object' || step === null) {
+                throw new Error(`${source}: each step must be an object`);
+            }
+            const s = step;
+            if (typeof s.name !== 'string') {
+                throw new Error(`${source}: each step must have a string "name" field`);
+            }
+            // Deterministic steps require type and command
+            if (s.type === 'deterministic') {
+                if (typeof s.command !== 'string') {
+                    throw new Error(`${source}: deterministic step "${s.name}" must have a "command" field`);
+                }
+            }
+            else {
+                // Agent steps (type undefined or 'agent') require agent and task
+                if (typeof s.agent !== 'string' || typeof s.task !== 'string') {
+                    throw new Error(`${source}: agent step "${s.name}" must have "agent" and "task" string fields`);
+                }
+            }
+        }
+        // Validate DAG: check for unknown dependencies and cycles
+        const stepNames = new Set(w.steps.map((s) => s.name));
+        for (const step of w.steps) {
+            if (step.dependsOn) {
+                for (const dep of step.dependsOn) {
+                    if (!stepNames.has(dep)) {
+                        throw new Error(`${source}: step "${step.name}" depends on unknown step "${dep}"`);
+                    }
+                }
+            }
+        }
+        this.detectCycles(w.steps, source, w.name);
+        this.detectLeadWorkerDeadlock(w.steps, agents, source, w.name);
+        // Warn if non-interactive agent task is excessively large before interpolation
+        for (const step of w.steps) {
+            if (step.type === 'deterministic' || step.type === 'worktree')
+                continue;
+            const agentDef = agents.find((a) => a.name === step.agent);
+            const isNonInteractive = agentDef?.interactive === false || ['worker', 'reviewer', 'analyst'].includes(agentDef?.preset ?? '');
+            if (isNonInteractive && (step.task ?? '').length > 10_000) {
+                console.warn(`[WorkflowRunner] Warning: non-interactive step "${step.name}" has a very large task (${step.task.length} chars). ` +
+                    `Consider pre-reading files in a deterministic step and injecting only the relevant excerpt.`);
+            }
+        }
+    }
+    detectCycles(steps, source, workflowName) {
+        const adj = new Map();
+        for (const step of steps) {
+            adj.set(step.name, step.dependsOn ?? []);
+        }
+        const visited = new Set();
+        const inStack = new Set();
+        const dfs = (node) => {
+            if (inStack.has(node)) {
+                throw new Error(`${source}: workflow "${workflowName}" contains a dependency cycle involving "${node}"`);
+            }
+            if (visited.has(node))
+                return;
+            inStack.add(node);
+            for (const dep of adj.get(node) ?? []) {
+                dfs(dep);
+            }
+            inStack.delete(node);
+            visited.add(node);
+        };
+        for (const step of steps) {
+            dfs(step.name);
+        }
+    }
+    detectLeadWorkerDeadlock(steps, agents, source, workflowName) {
+        // Build a map of step name → steps that depend on it
+        const downstreamOf = new Map();
+        for (const step of steps) {
+            for (const dep of step.dependsOn ?? []) {
+                if (!downstreamOf.has(dep))
+                    downstreamOf.set(dep, []);
+                downstreamOf.get(dep).push(step.name);
+            }
+        }
+        for (const step of steps) {
+            // Only check interactive agent steps (leads)
+            if (step.type === 'deterministic' || step.type === 'worktree')
+                continue;
+            const agentDef = agents.find((a) => a.name === step.agent);
+            // Skip non-interactive agents — they can't wait for channel signals
+            if (agentDef?.interactive === false ||
+                agentDef?.preset === 'worker' ||
+                agentDef?.preset === 'reviewer' ||
+                agentDef?.preset === 'analyst')
+                continue;
+            const downstream = downstreamOf.get(step.name) ?? [];
+            if (downstream.length === 0)
+                continue;
+            // Check if the task mentions downstream step names in a "waiting" context
+            const task = step.task ?? '';
+            const waitingKeywords = /\b(wait|waiting|monitor|check inbox|check.*channel|DONE|_DONE|signal)\b/i;
+            if (!waitingKeywords.test(task))
+                continue;
+            // Check if any downstream step name appears in the task
+            const mentioned = downstream.filter((name) => task.includes(name));
+            if (mentioned.length > 0) {
+                throw new Error(`${source}: workflow "${workflowName}" likely has a lead\u2194worker deadlock. ` +
+                    `Step "${step.name}" (interactive lead) mentions downstream step(s) [${mentioned.join(', ')}] in its task ` +
+                    `and appears to wait for their signals, but those steps can't start until "${step.name}" completes. ` +
+                    `Fix: make workers depend on a shared upstream step (e.g. "context"), not on the lead step. ` +
+                    `See tests/workflows/README.md rule #6.`);
+            }
+        }
+    }
+    // ── 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);
+                    }
+                }
+            }
+        }
+        return resolved;
+    }
+    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);
+        });
+    }
+    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);
+    }
+    /** Build a nested context from completed step outputs for {{steps.X.output}} resolution. */
+    buildStepOutputContext(stepStates, runId) {
+        const steps = {};
+        for (const [name, state] of stepStates) {
+            if (state.row.status === 'completed' && state.row.output !== undefined) {
+                steps[name] = { output: state.row.output };
+            }
+            else if (state.row.status === 'completed' && runId) {
+                // Recover from persisted output on disk (e.g., after restart)
+                const persisted = this.loadStepOutput(runId, name);
+                if (persisted) {
+                    state.row.output = persisted;
+                    steps[name] = { output: persisted };
+                }
+            }
+        }
+        return { steps };
+    }
+    /** 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);
+        });
+    }
+    // ── Execution ───────────────────────────────────────────────────────────
+    /** Execute a named workflow from a validated config. */
+    async execute(config, workflowName, vars) {
+        const resolved = vars ? this.resolveVariables(config, vars) : config;
+        const workflows = resolved.workflows ?? [];
+        const workflow = workflowName ? workflows.find((w) => w.name === workflowName) : workflows[0];
+        if (!workflow) {
+            throw new Error(workflowName ? `Workflow "${workflowName}" not found in config` : 'No workflows defined in config');
+        }
+        // Load and resolve custom step definitions
+        const customSteps = loadCustomSteps(this.cwd);
+        const resolvedSteps = resolveAllCustomSteps(workflow.steps, customSteps);
+        const resolvedWorkflow = { ...workflow, steps: resolvedSteps };
+        const runId = this.generateId();
+        const now = new Date().toISOString();
+        const run = {
+            id: runId,
+            workspaceId: this.workspaceId,
+            workflowName: resolvedWorkflow.name,
+            pattern: resolved.swarm.pattern,
+            status: 'pending',
+            config: resolved,
+            startedAt: now,
+            createdAt: now,
+            updatedAt: now,
+        };
+        await this.db.insertRun(run);
+        // Build step rows
+        const stepStates = new Map();
+        for (const step of resolvedWorkflow.steps) {
+            // Handle agent, deterministic, and worktree steps
+            const isNonAgent = step.type === 'deterministic' || step.type === 'worktree';
+            const stepRow = {
+                id: this.generateId(),
+                runId,
+                stepName: step.name,
+                agentName: isNonAgent ? null : (step.agent ?? null),
+                stepType: isNonAgent ? step.type : 'agent',
+                status: 'pending',
+                task: step.type === 'deterministic'
+                    ? (step.command ?? '')
+                    : step.type === 'worktree'
+                        ? (step.branch ?? '')
+                        : (step.task ?? ''),
+                dependsOn: step.dependsOn ?? [],
+                retryCount: 0,
+                createdAt: now,
+                updatedAt: now,
+            };
+            await this.db.insertStep(stepRow);
+            stepStates.set(step.name, { row: stepRow });
+        }
+        return this.runWorkflowCore({
+            run,
+            workflow: resolvedWorkflow,
+            config: resolved,
+            stepStates,
+            isResume: false,
+        });
+    }
+    /** Resume a previously paused or partially completed run. */
+    async resume(runId, vars) {
+        const run = await this.db.getRun(runId);
+        if (!run) {
+            throw new Error(`Run "${runId}" not found`);
+        }
+        if (run.status !== 'running' && run.status !== 'failed') {
+            throw new Error(`Run "${runId}" is in status "${run.status}" and cannot be resumed`);
+        }
+        const config = vars ? this.resolveVariables(run.config, vars) : run.config;
+        const workflows = config.workflows ?? [];
+        const workflow = workflows.find((w) => w.name === run.workflowName);
+        if (!workflow) {
+            throw new Error(`Workflow "${run.workflowName}" not found in stored config`);
+        }
+        const existingSteps = await this.db.getStepsByRunId(runId);
+        const stepStates = new Map();
+        for (const stepRow of existingSteps) {
+            stepStates.set(stepRow.stepName, { row: stepRow });
+        }
+        // Reset failed steps to pending for retry
+        for (const [, state] of stepStates) {
+            if (state.row.status === 'failed') {
+                state.row.status = 'pending';
+                state.row.error = undefined;
+                await this.db.updateStep(state.row.id, {
+                    status: 'pending',
+                    error: undefined,
+                    updatedAt: new Date().toISOString(),
+                });
+            }
+        }
+        return this.runWorkflowCore({
+            run,
+            workflow,
+            config,
+            stepStates,
+            isResume: true,
+        });
+    }
+    async runWorkflowCore(input) {
+        const { run, workflow, config, stepStates, isResume } = input;
+        const runId = run.id;
+        // Start execution
+        this.abortController = new AbortController();
+        this.paused = false;
+        this.currentConfig = config;
+        this.currentRunId = runId;
+        this.runStartTime = Date.now();
+        this.log(`Starting workflow "${workflow.name}" (${workflow.steps.length} steps)`);
+        // Initialize trajectory recording
+        this.trajectory = new WorkflowTrajectory(config.trajectories, runId, this.cwd);
+        try {
+            await this.updateRunStatus(runId, 'running');
+            if (!isResume) {
+                this.emit({ type: 'run:started', runId });
+            }
+            const pendingCount = [...stepStates.values()].filter((s) => s.row.status === 'pending').length;
+            if (isResume) {
+                await this.trajectory.start(workflow.name, workflow.steps.length, `Resumed run: ${pendingCount} pending steps of ${workflow.steps.length} total`, config.description, config.swarm.pattern);
+            }
+            else {
+                // Analyze DAG for trajectory context on first run
+                const dagInfo = this.analyzeDAG(workflow.steps);
+                await this.trajectory.start(workflow.name, workflow.steps.length, dagInfo, config.description, config.swarm.pattern);
+            }
+            const channel = config.swarm.channel ??
+                `wf-${this.sanitizeChannelName(config.name || run.workflowName)}-${this.generateShortId()}`;
+            this.channel = channel;
+            if (!config.swarm.channel) {
+                config.swarm.channel = channel;
+                await this.db.updateRun(runId, { config });
+            }
+            this.log('Resolving Relaycast API key...');
+            await this.ensureRelaycastApiKey(channel);
+            this.log('API key resolved');
+            if (this.relayApiKeyAutoCreated && this.relayApiKey) {
+                this.log(`Workspace created — follow this run in Relaycast:`);
+                this.log(`  RELAY_API_KEY=${this.relayApiKey}`);
+                this.log(`  Observer: https://observer.relaycast.dev (paste key above)`);
+                this.log(`  Channel: ${channel}`);
+            }
+            this.log('Starting broker...');
+            // Include a short run ID suffix in the broker name so each workflow execution
+            // registers a unique identity in Relaycast. Without this, re-running in the same
+            // workspace hits a 409 conflict because the previous run's agent is still registered.
+            const brokerBaseName = path.basename(this.cwd) || 'workflow';
+            const brokerName = `${brokerBaseName}-${runId.slice(0, 8)}`;
+            this.relay = new AgentRelay({
+                ...this.relayOptions,
+                brokerName,
+                channels: [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
+                // long-running PTY processes from earlier steps. 120s gives room to breathe.
+                requestTimeoutMs: this.relayOptions.requestTimeoutMs ?? 120_000,
+            });
+            // Wire PTY output dispatcher — routes chunks to per-agent listeners + activity logging
+            this.relay.onWorkerOutput = ({ name, chunk }) => {
+                const listener = this.ptyListeners.get(name);
+                if (listener)
+                    listener(chunk);
+                // Parse PTY output for high-signal activity
+                const stripped = WorkflowRunner.stripAnsi(chunk);
+                const shortName = name.replace(/-[a-f0-9]{6,}$/, '');
+                let activity;
+                if (/Read\(/.test(stripped)) {
+                    // Extract filename — path may be truncated at chunk boundary so require
+                    // at least a dir separator or 8+ chars to trust the basename.
+                    const m = stripped.match(/Read\(\s*~?([^\s)"']{8,})/);
+                    if (m) {
+                        const base = path.basename(m[1]);
+                        activity = base.length >= 3 ? `Reading ${base}` : 'Reading file...';
+                    }
+                    else {
+                        activity = 'Reading file...';
+                    }
+                }
+                else if (/Edit\(/.test(stripped)) {
+                    const m = stripped.match(/Edit\(\s*~?([^\s)"']{8,})/);
+                    if (m) {
+                        const base = path.basename(m[1]);
+                        activity = base.length >= 3 ? `Editing ${base}` : 'Editing file...';
+                    }
+                    else {
+                        activity = 'Editing file...';
+                    }
+                }
+                else if (/Bash\(/.test(stripped)) {
+                    // Extract a short preview of the command
+                    const m = stripped.match(/Bash\(\s*(.{1,40})/);
+                    activity = m ? `Running: ${m[1].trim()}...` : 'Running command...';
+                }
+                else if (/Explore\(/.test(stripped)) {
+                    const m = stripped.match(/Explore\(\s*(.{1,50})/);
+                    activity = m ? `Exploring: ${m[1].replace(/\).*/, '').trim()}` : 'Exploring codebase...';
+                }
+                else if (/Task\(/.test(stripped)) {
+                    activity = 'Running sub-agent...';
+                }
+                else if (/Sublimating|Thinking|Coalescing|Cultivating/.test(stripped)) {
+                    const m = stripped.match(/(\d+)s/);
+                    activity = m ? `Thinking... (${m[1]}s)` : 'Thinking...';
+                }
+                if (activity && this.lastActivity.get(name) !== activity) {
+                    this.lastActivity.set(name, activity);
+                    this.log(`[${shortName}] ${activity}`);
+                }
+            };
+            // Wire relay event hooks for rich console logging
+            this.relay.onMessageReceived = (msg) => {
+                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,}$/, '');
+                this.log(`[msg] ${fromShort} → ${toShort}: ${body}`);
+            };
+            this.relay.onAgentSpawned = (agent) => {
+                // Skip agents already managed by step execution
+                if (!this.activeAgentHandles.has(agent.name)) {
+                    this.log(`[spawned] ${agent.name} (${agent.runtime})`);
+                }
+            };
+            this.relay.onAgentExited = (agent) => {
+                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.onAgentIdle = ({ name, idleSecs }) => {
+                // Only log at 30s multiples to avoid watchdog spam
+                const bucket = Math.floor(idleSecs / 30) * 30;
+                if (bucket >= 30 && this.lastIdleLog.get(name) !== bucket) {
+                    this.lastIdleLog.set(name, bucket);
+                    const shortName = name.replace(/-[a-f0-9]{6,}$/, '');
+                    this.log(`[idle] ${shortName} silent for ${bucket}s`);
+                }
+            };
+            this.relaycast = undefined;
+            this.relaycastAgent = undefined;
+            // Wire broker stderr to console for observability
+            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, workflow.description);
+            }
+            this.log('Channel ready');
+            if (isResume) {
+                this.postToChannel(`Workflow **${workflow.name}** resumed — ${pendingCount} pending steps`);
+            }
+            else {
+                this.postToChannel(`Workflow **${workflow.name}** started — ${workflow.steps.length} steps, pattern: ${config.swarm.pattern}`);
+            }
+            const agentMap = new Map();
+            for (const agent of config.agents) {
+                agentMap.set(agent.name, agent);
+            }
+            // Run preflight checks before any steps (skip on resume)
+            if (!isResume && workflow.preflight?.length) {
+                await this.runPreflightChecks(workflow.preflight, runId);
+            }
+            // Pre-register all interactive agent steps with Relaycast before execution.
+            // This warms the broker's token cache so spawn_agent calls are instant cache
+            // hits rather than blocking on individual HTTP registrations per spawn.
+            // Agent names use the run ID prefix (deterministic) so we can predict them.
+            if (this.relay && !isResume) {
+                const agentPreflight = workflow.steps
+                    .filter((s) => s.type !== 'deterministic' && s.type !== 'worktree' && s.agent)
+                    .map((s) => {
+                    const agentDef = agentMap.get(s.agent);
+                    return agentDef && agentDef.interactive !== false
+                        ? { name: `${s.name}-${runId.slice(0, 8)}`, cli: agentDef.cli }
+                        : null;
+                })
+                    .filter((e) => e !== null);
+                if (agentPreflight.length > 0) {
+                    this.log(`Pre-registering ${agentPreflight.length} agents with Relaycast...`);
+                    await this.relay.preflightAgents(agentPreflight).catch((err) => {
+                        this.log(`[preflight-agents] warning: ${err.message} — continuing without pre-registration`);
+                    });
+                    this.log('Agent pre-registration complete');
+                }
+            }
+            this.log(`Executing ${workflow.steps.length} steps (pattern: ${config.swarm.pattern})`);
+            await this.executeSteps(workflow, stepStates, agentMap, config.errorHandling, runId);
+            const allCompleted = [...stepStates.values()].every((s) => s.row.status === 'completed' || s.row.status === 'skipped');
+            if (allCompleted) {
+                this.log('Workflow completed successfully');
+                await this.updateRunStatus(runId, 'completed');
+                this.emit({ type: 'run:completed', runId });
+                const outcomes = this.collectOutcomes(stepStates, workflow.steps);
+                const summary = this.trajectory.buildRunSummary(outcomes);
+                const confidence = this.trajectory.computeConfidence(outcomes);
+                await this.trajectory.complete(summary, confidence, {
+                    learnings: this.trajectory.extractLearnings(outcomes),
+                    challenges: this.trajectory.extractChallenges(outcomes),
+                });
+                this.postCompletionReport(workflow.name, outcomes, summary, confidence);
+                this.logRunSummary(workflow.name, outcomes, runId);
+            }
+            else {
+                const failedStep = [...stepStates.values()].find((s) => s.row.status === 'failed');
+                const errorMsg = failedStep?.row.error ?? 'One or more steps failed';
+                await this.updateRunStatus(runId, 'failed', errorMsg);
+                this.emit({ type: 'run:failed', runId, error: errorMsg });
+                const outcomes = this.collectOutcomes(stepStates, workflow.steps);
+                this.postFailureReport(workflow.name, outcomes, errorMsg);
+                this.logRunSummary(workflow.name, outcomes, runId);
+                await this.trajectory.abandon(errorMsg);
+            }
+        }
+        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') {
+                this.emit({ type: 'run:cancelled', runId });
+                this.postToChannel(`Workflow **${workflow.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);
+            }
+        }
+        finally {
+            for (const stream of this.ptyLogStreams.values())
+                stream.end();
+            this.ptyLogStreams.clear();
+            this.ptyOutputBuffers.clear();
+            this.ptyListeners.clear();
+            this.unsubBrokerStderr?.();
+            this.unsubBrokerStderr = undefined;
+            // Null out relay event hooks to prevent leaks
+            if (this.relay) {
+                this.relay.onMessageReceived = null;
+                this.relay.onAgentSpawned = null;
+                this.relay.onAgentExited = null;
+                this.relay.onAgentIdle = null;
+                this.relay.onWorkerOutput = null;
+            }
+            this.lastIdleLog.clear();
+            this.lastActivity.clear();
+            this.log('Shutting down broker...');
+            await this.relay?.shutdown();
+            this.relay = undefined;
+            this.runStartTime = undefined;
+            this.relaycast = undefined;
+            this.relaycastAgent = undefined;
+            this.channel = undefined;
+            this.trajectory = undefined;
+            this.abortController = undefined;
+            this.currentConfig = undefined;
+            this.currentRunId = undefined;
+            this.activeAgentHandles.clear();
+        }
+        const finalRun = await this.db.getRun(runId);
+        return finalRun ?? run;
+    }
+    /** Pause execution. Currently-running steps will finish but no new steps start. */
+    pause() {
+        this.paused = true;
+    }
+    /** Resume after a pause(). */
+    unpause() {
+        this.paused = false;
+        this.pauseResolver?.();
+        this.pauseResolver = undefined;
+    }
+    /** Abort the current run. Running agents are released. */
+    abort() {
+        // Unblock waitIfPaused() so the run loop can exit
+        this.pauseResolver?.();
+        this.pauseResolver = undefined;
+        this.abortController?.abort();
+    }
+    // ── 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'
+                ? 'continue'
+                : 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,
+                    });
+                }
+            }
+            // 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);
+            }
+        }
+    }
+    findReadySteps(steps, stepStates) {
+        return steps.filter((step) => {
+            const state = stepStates.get(step.name);
+            if (!state || state.row.status !== 'pending')
+                return false;
+            const deps = step.dependsOn ?? [];
+            return deps.every((dep) => {
+                const depState = stepStates.get(dep);
+                return depState && (depState.row.status === 'completed' || depState.row.status === 'skipped');
+            });
+        });
+    }
+    /**
+     * Execute preflight checks before any workflow steps.
+     * All checks must pass or the workflow fails immediately.
+     */
+    async runPreflightChecks(checks, runId) {
+        this.postToChannel(`Running ${checks.length} preflight check(s)...`);
+        for (const check of checks) {
+            this.checkAborted();
+            const description = check.description ?? check.command.slice(0, 50);
+            this.postToChannel(`**[preflight]** ${description}`);
+            try {
+                const output = await new Promise((resolve, reject) => {
+                    const child = cpSpawn('sh', ['-c', check.command], {
+                        stdio: 'pipe',
+                        cwd: this.cwd,
+                        env: { ...process.env },
+                    });
+                    const stdoutChunks = [];
+                    const stderrChunks = [];
+                    // Wire abort signal
+                    const abortSignal = this.abortController?.signal;
+                    let abortHandler;
+                    if (abortSignal && !abortSignal.aborted) {
+                        abortHandler = () => {
+                            child.kill('SIGTERM');
+                        };
+                        abortSignal.addEventListener('abort', abortHandler, { once: true });
+                    }
+                    // 30s timeout for preflight checks
+                    const timer = setTimeout(() => {
+                        child.kill('SIGTERM');
+                        reject(new Error(`Preflight check timed out: ${description}`));
+                    }, 30_000);
+                    child.stdout?.on('data', (chunk) => {
+                        stdoutChunks.push(chunk.toString());
+                    });
+                    child.stderr?.on('data', (chunk) => {
+                        stderrChunks.push(chunk.toString());
+                    });
+                    child.on('close', (code) => {
+                        clearTimeout(timer);
+                        if (abortHandler && abortSignal) {
+                            abortSignal.removeEventListener('abort', abortHandler);
+                        }
+                        if (abortSignal?.aborted) {
+                            reject(new Error('Preflight check aborted'));
+                            return;
+                        }
+                        // Non-zero exit code is a failure
+                        if (code !== 0 && code !== null) {
+                            const stderr = stderrChunks.join('');
+                            reject(new Error(`Preflight check failed (exit ${code})${stderr ? `: ${stderr.slice(0, 200)}` : ''}`));
+                            return;
+                        }
+                        resolve(stdoutChunks.join(''));
+                    });
+                    child.on('error', (err) => {
+                        clearTimeout(timer);
+                        if (abortHandler && abortSignal) {
+                            abortSignal.removeEventListener('abort', abortHandler);
+                        }
+                        reject(new Error(`Preflight check error: ${err.message}`));
+                    });
+                });
+                // Check failIf condition
+                if (check.failIf) {
+                    const trimmedOutput = output.trim();
+                    if (check.failIf === 'non-empty' && trimmedOutput.length > 0) {
+                        throw new Error(`Preflight failed: output is non-empty\n${trimmedOutput.slice(0, 200)}`);
+                    }
+                    if (check.failIf === 'empty' && trimmedOutput.length === 0) {
+                        throw new Error('Preflight failed: output is empty');
+                    }
+                    // Treat as regex pattern
+                    if (check.failIf !== 'non-empty' && check.failIf !== 'empty') {
+                        const regex = new RegExp(check.failIf);
+                        if (regex.test(output)) {
+                            throw new Error(`Preflight failed: output matches pattern "${check.failIf}"`);
+                        }
+                    }
+                }
+                // Check successIf condition
+                if (check.successIf) {
+                    const regex = new RegExp(check.successIf);
+                    if (!regex.test(output)) {
+                        throw new Error(`Preflight failed: output does not match required pattern "${check.successIf}"`);
+                    }
+                }
+                this.postToChannel(`**[preflight]** ${description} — passed`);
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                this.postToChannel(`**[preflight]** ${description} — FAILED: ${errorMsg}`);
+                throw new Error(`Preflight check failed: ${errorMsg}`);
+            }
+        }
+        this.postToChannel('All preflight checks passed');
+    }
+    /** Check if a step is deterministic (shell command) vs agent (LLM-powered). */
+    isDeterministicStep(step) {
+        return step.type === 'deterministic';
+    }
+    /** Check if a step is a worktree (git worktree setup) step. */
+    isWorktreeStep(step) {
+        return step.type === 'worktree';
+    }
+    async executeStep(step, stepStates, agentMap, errorHandling, runId) {
+        // Branch: deterministic steps execute shell commands
+        if (this.isDeterministicStep(step)) {
+            return this.executeDeterministicStep(step, stepStates, runId);
+        }
+        // Branch: worktree steps set up git worktrees
+        if (this.isWorktreeStep(step)) {
+            return this.executeWorktreeStep(step, stepStates, runId);
+        }
+        // Agent step execution
+        return this.executeAgentStep(step, stepStates, agentMap, errorHandling, runId);
+    }
+    /**
+     * Execute a deterministic step (shell command).
+     * Fast, reliable, $0 LLM cost.
+     */
+    async executeDeterministicStep(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.startedAt = new Date().toISOString();
+        await this.db.updateStep(state.row.id, {
+            status: 'running',
+            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;
+        });
+        try {
+            const output = await new Promise((resolve, reject) => {
+                const child = cpSpawn('sh', ['-c', resolvedCommand], {
+                    stdio: 'pipe',
+                    cwd: this.cwd,
+                    env: { ...process.env },
+                });
+                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 });
+                }
+                // Handle timeout
+                let timedOut = false;
+                let timer;
+                if (step.timeoutMs) {
+                    timer = setTimeout(() => {
+                        timedOut = true;
+                        child.kill('SIGTERM');
+                        setTimeout(() => child.kill('SIGKILL'), 5000);
+                    }, 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);
+                    }
+                    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('');
+                    // 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)}` : ''}`));
+                        return;
+                    }
+                    resolve(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}`));
+                });
+            });
+            // Mark completed
+            state.row.status = 'completed';
+            state.row.output = output;
+            state.row.completedAt = new Date().toISOString();
+            await this.db.updateStep(state.row.id, {
+                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}]** Completed (deterministic)\n${output.slice(0, 500)}${output.length > 500 ? '\n...(truncated)' : ''}`);
+        }
+        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}`);
+        }
+    }
+    /**
+     * 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}`);
+        this.checkAborted();
+        // Mark step as running
+        state.row.status = 'running';
+        state.row.startedAt = new Date().toISOString();
+        await this.db.updateStep(state.row.id, {
+            status: 'running',
+            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;
+        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(this.cwd, 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: this.cwd,
+                    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}`);
+            }
+            const output = await new Promise((resolve, reject) => {
+                const child = cpSpawn('sh', ['-c', worktreeCmd], {
+                    stdio: 'pipe',
+                    cwd: this.cwd,
+                    env: { ...process.env },
+                });
+                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 });
+                }
+                // Handle timeout
+                let timedOut = false;
+                let timer;
+                if (step.timeoutMs) {
+                    timer = setTimeout(() => {
+                        timedOut = true;
+                        child.kill('SIGTERM');
+                        setTimeout(() => child.kill('SIGKILL'), 5000);
+                    }, 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);
+                    }
+                    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 stderr = stderrChunks.join('');
+                    if (code !== 0 && code !== null) {
+                        reject(new Error(`git worktree add failed with exit code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ''}`));
+                        return;
+                    }
+                    // Output the worktree path for downstream steps
+                    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}`));
+                });
+            });
+            // Mark completed
+            state.row.status = 'completed';
+            state.row.output = output;
+            state.row.completedAt = new Date().toISOString();
+            await this.db.updateStep(state.row.id, {
+                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)' : ''}`);
+        }
+        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}`);
+        }
+    }
+    /**
+     * Execute an agent step (LLM-powered).
+     */
+    async executeAgentStep(step, stepStates, agentMap, errorHandling, runId) {
+        const state = stepStates.get(step.name);
+        if (!state)
+            throw new Error(`Step state not found: ${step.name}`);
+        const agentName = step.agent;
+        if (!agentName) {
+            throw new Error(`Step "${step.name}" is missing required "agent" field`);
+        }
+        const rawAgentDef = agentMap.get(agentName);
+        if (!rawAgentDef) {
+            throw new Error(`Agent "${agentName}" not found in config`);
+        }
+        const agentDef = WorkflowRunner.resolveAgentDef(rawAgentDef);
+        const maxRetries = step.retries ?? agentDef.constraints?.retries ?? errorHandling?.maxRetries ?? 0;
+        const retryDelay = errorHandling?.retryDelayMs ?? 1000;
+        const timeoutMs = step.timeoutMs ?? agentDef.constraints?.timeoutMs ?? this.currentConfig?.swarm?.timeoutMs;
+        let lastError;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            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, {
+                    retryCount: attempt,
+                    updatedAt: new Date().toISOString(),
+                });
+                await this.trajectory?.stepRetrying(step, attempt, maxRetries);
+                await this.delay(retryDelay);
+            }
+            try {
+                // Mark step as running
+                state.row.status = 'running';
+                state.row.startedAt = new Date().toISOString();
+                await this.db.updateStep(state.row.id, {
+                    status: 'running',
+                    startedAt: state.row.startedAt,
+                    updatedAt: new Date().toISOString(),
+                });
+                this.emit({ type: 'step:started', runId, stepName: step.name });
+                this.postToChannel(`**[${step.name}]** Started (agent: ${agentDef.name})`);
+                await this.trajectory?.stepStarted(step, agentDef.name);
+                // Resolve step-output variables (e.g. {{steps.plan.output}}) at execution time
+                const stepOutputContext = this.buildStepOutputContext(stepStates, runId);
+                let resolvedTask = this.interpolateStepTask(step.task ?? '', stepOutputContext);
+                // If this is an interactive agent, append awareness of non-interactive workers
+                // so the lead knows not to message them and to use step output chaining instead
+                if (agentDef.interactive !== false) {
+                    const nonInteractiveInfo = this.buildNonInteractiveAwareness(agentMap, stepStates);
+                    if (nonInteractiveInfo) {
+                        resolvedTask += nonInteractiveInfo;
+                    }
+                }
+                // Spawn agent via AgentRelay
+                this.log(`[${step.name}] Spawning agent "${agentDef.name}" (cli: ${agentDef.cli})`);
+                const resolvedStep = { ...step, task: resolvedTask };
+                const output = await this.spawnAndWait(agentDef, resolvedStep, timeoutMs);
+                this.log(`[${step.name}] Agent "${agentDef.name}" exited`);
+                // Run verification if configured
+                if (step.verification) {
+                    this.runVerification(step.verification, output, step.name, resolvedTask);
+                }
+                // Mark completed
+                state.row.status = 'completed';
+                state.row.output = output;
+                state.row.completedAt = new Date().toISOString();
+                await this.db.updateStep(state.row.id, {
+                    status: 'completed',
+                    output,
+                    completedAt: state.row.completedAt,
+                    updatedAt: new Date().toISOString(),
+                });
+                // Persist step output to disk so it survives restarts and is inspectable
+                await this.persistStepOutput(runId, step.name, output);
+                this.emit({ type: 'step:completed', runId, stepName: step.name, output });
+                this.postToChannel(`**[${step.name}]** Completed\n${output.slice(0, 500)}${output.length > 500 ? '\n...(truncated)' : ''}`);
+                await this.trajectory?.stepCompleted(step, output, attempt + 1);
+                return;
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err.message : String(err);
+            }
+        }
+        // All retries exhausted — record root-cause diagnosis and mark failed
+        const nonInteractive = agentDef.interactive === false || ['worker', 'reviewer', 'analyst'].includes(agentDef.preset ?? '');
+        const verificationValue = typeof step.verification === 'object' && 'value' in step.verification
+            ? String(step.verification.value)
+            : undefined;
+        await this.trajectory?.stepFailed(step, lastError ?? 'Unknown error', maxRetries + 1, maxRetries, {
+            agent: agentName,
+            nonInteractive,
+            verificationValue,
+        });
+        this.postToChannel(`**[${step.name}]** Failed: ${lastError ?? 'Unknown error'}`);
+        await this.markStepFailed(state, lastError ?? 'Unknown error', runId);
+        throw new Error(`Step "${step.name}" failed after ${maxRetries} retries: ${lastError ?? 'Unknown error'}`);
+    }
+    /**
+     * Build the CLI command and arguments for a non-interactive agent execution.
+     * Each CLI has a specific flag for one-shot prompt mode.
+     */
+    static buildNonInteractiveCommand(cli, task, extraArgs = []) {
+        switch (cli) {
+            case 'claude':
+                // --dangerously-skip-permissions prevents any tool-use permission prompt
+                // from blocking the process when stdio is piped (no TTY available).
+                return { cmd: 'claude', args: ['-p', '--dangerously-skip-permissions', task, ...extraArgs] };
+            case 'codex':
+                return { cmd: 'codex', args: ['exec', task, ...extraArgs] };
+            case 'gemini':
+                return { cmd: 'gemini', args: ['-p', task, ...extraArgs] };
+            case 'opencode':
+                return { cmd: 'opencode', args: ['--prompt', task, ...extraArgs] };
+            case 'droid':
+                return { cmd: 'droid', args: ['exec', task, ...extraArgs] };
+            case 'aider':
+                return { cmd: 'aider', args: ['--message', task, '--yes-always', '--no-git', ...extraArgs] };
+            case 'goose':
+                return { cmd: 'goose', args: ['run', '--text', task, '--no-session', ...extraArgs] };
+        }
+    }
+    /**
+     * Apply preset defaults to an agent definition.
+     * Explicit fields on the definition always win over preset-inferred defaults.
+     */
+    static resolveAgentDef(def) {
+        if (!def.preset)
+            return def;
+        const nonInteractivePresets = ['worker', 'reviewer', 'analyst'];
+        const defaults = nonInteractivePresets.includes(def.preset)
+            ? { interactive: false }
+            : {};
+        // Explicit fields on the def always win
+        return { ...defaults, ...def };
+    }
+    /**
+     * Returns a preset-specific prefix that is prepended to the non-interactive
+     * enforcement block in execNonInteractive.
+     */
+    /**
+     * Returns a prefix injected into the task prompt for non-interactive agents.
+     * Lead agents are always interactive (PTY), so they never reach execNonInteractive
+     * and there is no 'lead' case here.
+     */
+    buildPresetInjection(preset) {
+        switch (preset) {
+            case 'worker':
+                return ('You are a non-interactive worker agent. Produce clean, structured output to stdout.\n' +
+                    'Do NOT use relay_spawn, add_agent, or any MCP tool to spawn sub-agents.\n' +
+                    'Do NOT use relay_send or any Relaycast messaging tools — you have no relay connection.\n\n');
+            case 'reviewer':
+                return ('You are a non-interactive reviewer agent. Read the specified files/artifacts and produce a clear verdict.\n' +
+                    'Do NOT spawn sub-agents or use any Relaycast messaging tools.\n\n');
+            case 'analyst':
+                return ('You are a non-interactive analyst agent. Read the specified code/files and write your findings.\n' +
+                    'Do NOT spawn sub-agents or use any Relaycast messaging tools.\n\n');
+            default:
+                return '';
+        }
+    }
+    /**
+     * Execute an agent as a non-interactive subprocess.
+     * No PTY, no relay messaging, no /exit injection. The process receives its task
+     * as a CLI argument and stdout is captured as the step output.
+     */
+    async execNonInteractive(agentDef, step, timeoutMs) {
+        const agentName = `${step.name}-${this.generateShortId()}`;
+        const modelArgs = agentDef.constraints?.model ? ['--model', agentDef.constraints.model] : [];
+        // Append strict deliverable enforcement — non-interactive agents MUST produce
+        // clear, structured output since there's no opportunity for follow-up or clarification.
+        const presetPrefix = this.buildPresetInjection(agentDef.preset);
+        const taskWithDeliverable = presetPrefix +
+            step.task +
+            '\n\n---\n' +
+            'IMPORTANT: You are running as a non-interactive subprocess. ' +
+            'Do NOT call relay_spawn, add_agent, or any MCP tool to spawn or manage other agents.\n\n' +
+            'CRITICAL REQUIREMENT — YOU MUST FOLLOW THIS EXACTLY:\n' +
+            'You are running in non-interactive mode. There is NO opportunity for follow-up, ' +
+            'clarification, or additional input. Your stdout output is your ONLY deliverable.\n\n' +
+            'You MUST:\n' +
+            '1. Complete the ENTIRE task in a single pass — no partial work, no "I\'ll continue later"\n' +
+            '2. Print your COMPLETE deliverable to stdout — this is the ONLY output that will be captured\n' +
+            '3. Be thorough and self-contained — another agent will consume your output with zero context about your process\n' +
+            '4. End with a clear summary of what was accomplished and any artifacts produced\n\n' +
+            'DO NOT:\n' +
+            '- Ask questions or request clarification (there is no one to answer)\n' +
+            '- Output partial results expecting a follow-up (there will be none)\n' +
+            '- Skip steps or leave work incomplete\n' +
+            '- Output only status messages without the actual deliverable content';
+        const { cmd, args } = WorkflowRunner.buildNonInteractiveCommand(agentDef.cli, taskWithDeliverable, modelArgs);
+        // Open a log file for dashboard observability
+        const logsDir = this.getWorkerLogsDir();
+        const logPath = path.join(logsDir, `${agentName}.log`);
+        const logStream = createWriteStream(logPath, { flags: 'a' });
+        // Register in workers.json with interactive: false metadata
+        this.registerWorker(agentName, agentDef.cli, step.task ?? '', undefined, false);
+        // Register agent in Relaycast for observability
+        let stopHeartbeat;
+        if (this.relayApiKey) {
+            const agentClient = await this.registerRelaycastExternalAgent(agentName, `Non-interactive workflow agent for step "${step.name}" (${agentDef.cli})`).catch((err) => {
+                console.warn(`[WorkflowRunner] Failed to register ${agentName} in Relaycast:`, err?.message ?? err);
+                return null;
+            });
+            if (agentClient) {
+                stopHeartbeat = this.startRelaycastHeartbeat(agentClient);
+            }
+        }
+        // Post assignment notification (no task content — task arrives via direct broker injection)
+        this.postToChannel(`**[${step.name}]** Assigned to \`${agentName}\` (non-interactive)`);
+        const stdoutChunks = [];
+        const stderrChunks = [];
+        try {
+            const output = await new Promise((resolve, reject) => {
+                const child = cpSpawn(cmd, args, {
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                    cwd: agentDef.cwd ? path.resolve(this.cwd, agentDef.cwd) : this.cwd,
+                    env: this.getRelayEnv() ?? { ...process.env },
+                });
+                // Update workers.json with PID now that we have it
+                this.registerWorker(agentName, agentDef.cli, step.task ?? '', child.pid, false);
+                // Wire abort signal so runner.abort() kills the child process
+                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 });
+                }
+                // Heartbeat so a slow non-interactive agent doesn't look frozen.
+                // Each tick shows the last substantive line received — gives insight
+                // without flooding the log with raw model output.
+                const startedAt = Date.now();
+                let lastHeartbeatLine = '';
+                const heartbeat = setInterval(() => {
+                    const elapsed = Math.round((Date.now() - startedAt) / 1000);
+                    const suffix = lastHeartbeatLine ? ` — ${lastHeartbeatLine.slice(0, 80)}` : '';
+                    this.log(`[${step.name}] still running (${elapsed}s)${suffix}`);
+                    lastHeartbeatLine = '';
+                }, 30_000);
+                child.stdout?.on('data', (chunk) => {
+                    const text = chunk.toString();
+                    stdoutChunks.push(text);
+                    logStream.write(text);
+                    // Track last substantive line for the next heartbeat
+                    const line = text
+                        .split('\n')
+                        .map((l) => l.trim())
+                        .filter(Boolean)
+                        .at(-1) ?? '';
+                    if (line)
+                        lastHeartbeatLine = line;
+                });
+                child.stderr?.on('data', (chunk) => {
+                    const text = chunk.toString();
+                    stderrChunks.push(text);
+                    logStream.write(`[stderr] ${text}`);
+                });
+                // Handle timeout
+                let timedOut = false;
+                let timer;
+                if (timeoutMs) {
+                    timer = setTimeout(() => {
+                        timedOut = true;
+                        child.kill('SIGTERM');
+                        // Give process time to clean up, then force kill
+                        setTimeout(() => child.kill('SIGKILL'), 5000);
+                    }, timeoutMs);
+                }
+                child.on('close', (code) => {
+                    clearInterval(heartbeat);
+                    if (timer)
+                        clearTimeout(timer);
+                    if (abortHandler && abortSignal) {
+                        abortSignal.removeEventListener('abort', abortHandler);
+                    }
+                    const stdout = stdoutChunks.join('');
+                    if (abortSignal?.aborted) {
+                        reject(new Error(`Step "${step.name}" aborted`));
+                        return;
+                    }
+                    if (timedOut) {
+                        reject(new Error(`Step "${step.name}" timed out after ${timeoutMs ?? 'unknown'}ms`));
+                        return;
+                    }
+                    if (code !== 0 && code !== null) {
+                        const stderr = stderrChunks.join('');
+                        reject(new Error(`Step "${step.name}" exited with code ${code}${stderr ? `: ${stderr.slice(0, 500)}` : ''}`));
+                        return;
+                    }
+                    resolve(stdout);
+                });
+                child.on('error', (err) => {
+                    clearInterval(heartbeat);
+                    if (timer)
+                        clearTimeout(timer);
+                    if (abortHandler && abortSignal) {
+                        abortSignal.removeEventListener('abort', abortHandler);
+                    }
+                    reject(new Error(`Failed to spawn ${cmd}: ${err.message}`));
+                });
+            });
+            return output;
+        }
+        finally {
+            stopHeartbeat?.();
+            logStream.end();
+            this.unregisterWorker(agentName);
+        }
+    }
+    async spawnAndWait(agentDef, step, timeoutMs) {
+        // Branch: non-interactive agents run as simple subprocesses
+        if (agentDef.interactive === false) {
+            return this.execNonInteractive(agentDef, step, timeoutMs);
+        }
+        if (!this.relay) {
+            throw new Error('AgentRelay not initialized');
+        }
+        // Deterministic name: step name + first 8 chars of run ID.
+        // This matches the names pre-registered in preflightAgents(), so the broker
+        // hits its token cache instantly instead of making a fresh Relaycast HTTP call.
+        // On retry the broker may suffix a UUID (409 conflict) — that's fine, the agent
+        // still works, just without the cache benefit.
+        let agentName = `${step.name}-${(this.currentRunId ?? this.generateShortId()).slice(0, 8)}`;
+        // Only inject delegation guidance for lead/coordinator agents, not spokes/workers.
+        // In non-hub patterns (pipeline, dag, etc.) every agent is autonomous so they all get it.
+        const role = agentDef.role?.toLowerCase() ?? '';
+        const nameLC = agentDef.name.toLowerCase();
+        const isHub = WorkflowRunner.HUB_ROLES.has(nameLC) || [...WorkflowRunner.HUB_ROLES].some((r) => role.includes(r));
+        const pattern = this.currentConfig?.swarm.pattern;
+        const isHubPattern = pattern && WorkflowRunner.HUB_PATTERNS.has(pattern);
+        const delegationGuidance = isHub || !isHubPattern ? this.buildDelegationGuidance(agentDef.cli, timeoutMs) : '';
+        // Non-claude CLIs (codex, gemini, etc.) don't auto-register with Relaycast
+        // via the MCP system prompt the way claude does. Inject an explicit preamble
+        // so they call register() before any other relay tool.
+        const relayRegistrationNote = this.buildRelayRegistrationNote(agentDef.cli, agentName);
+        const taskWithExit = step.task +
+            (relayRegistrationNote ? '\n\n' + relayRegistrationNote : '') +
+            (delegationGuidance ? '\n\n' + delegationGuidance + '\n' : '') +
+            '\n\n---\n' +
+            'IMPORTANT: When you have fully completed this task, you MUST self-terminate by either: ' +
+            '(a) calling remove_agent(name: "<your-agent-name>", reason: "task completed") — preferred, or ' +
+            '(b) outputting the exact text "/exit" on its own line as a fallback. ' +
+            'Do not wait for further input — terminate immediately after finishing. ' +
+            'Do NOT spawn sub-agents unless the task explicitly requires it.';
+        // Register PTY output listener before spawning so we capture everything
+        this.ptyOutputBuffers.set(agentName, []);
+        // Open a log file so `agents:logs <name>` works for workflow-spawned agents
+        const logsDir = this.getWorkerLogsDir();
+        const logStream = createWriteStream(path.join(logsDir, `${agentName}.log`), { flags: 'a' });
+        this.ptyLogStreams.set(agentName, logStream);
+        this.ptyListeners.set(agentName, (chunk) => {
+            const stripped = WorkflowRunner.stripAnsi(chunk);
+            this.ptyOutputBuffers.get(agentName)?.push(stripped);
+            // Write raw output (with ANSI codes) to log file so dashboard's
+            // XTermLogViewer can render colors/formatting natively via xterm.js
+            logStream.write(chunk);
+        });
+        const agentChannels = this.channel ? [this.channel] : agentDef.channels;
+        let agent;
+        let exitResult = 'unknown';
+        let stopHeartbeat;
+        let ptyChunks = [];
+        try {
+            agent = await this.relay.spawnPty({
+                name: agentName,
+                cli: agentDef.cli,
+                model: agentDef.constraints?.model,
+                args: [],
+                channels: agentChannels,
+                task: taskWithExit,
+                idleThresholdSecs: agentDef.constraints?.idleThresholdSecs,
+                cwd: agentDef.cwd ? path.resolve(this.cwd, agentDef.cwd) : undefined,
+            });
+            // Re-key PTY maps if broker assigned a different name than requested
+            if (agent.name !== agentName) {
+                const oldName = agentName;
+                this.ptyOutputBuffers.set(agent.name, this.ptyOutputBuffers.get(oldName) ?? []);
+                this.ptyOutputBuffers.delete(oldName);
+                // Close old log stream and rename the file to match the new agent name
+                const oldLogPath = path.join(logsDir, `${oldName}.log`);
+                const newLogPath = path.join(logsDir, `${agent.name}.log`);
+                const oldLogStream = this.ptyLogStreams.get(oldName);
+                if (oldLogStream) {
+                    oldLogStream.end();
+                    this.ptyLogStreams.delete(oldName);
+                    try {
+                        renameSync(oldLogPath, newLogPath);
+                    }
+                    catch {
+                        // File may not exist yet if no output was written
+                    }
+                }
+                // Open new log stream with the correct name
+                const newLogStream = createWriteStream(newLogPath, { flags: 'a' });
+                this.ptyLogStreams.set(agent.name, newLogStream);
+                // Update listener to use the new log stream
+                const oldListener = this.ptyListeners.get(oldName);
+                if (oldListener) {
+                    this.ptyListeners.delete(oldName);
+                    this.ptyListeners.set(agent.name, (chunk) => {
+                        const stripped = WorkflowRunner.stripAnsi(chunk);
+                        this.ptyOutputBuffers.get(agent.name)?.push(stripped);
+                        newLogStream.write(chunk);
+                    });
+                }
+                agentName = agent.name;
+            }
+            // Register in workers.json so `agents:kill` can find this agent
+            let workerPid;
+            try {
+                const rawAgents = await this.relay.listAgentsRaw();
+                workerPid = rawAgents.find((a) => a.name === agentName)?.pid ?? undefined;
+            }
+            catch {
+                // Best-effort PID lookup
+            }
+            this.registerWorker(agentName, agentDef.cli, step.task ?? '', workerPid);
+            // Register the spawned agent in Relaycast for observability + start heartbeat
+            if (this.relayApiKey) {
+                const agentClient = await this.registerRelaycastExternalAgent(agent.name, `Workflow agent for step "${step.name}" (${agentDef.cli})`).catch((err) => {
+                    console.warn(`[WorkflowRunner] Failed to register ${agent.name} in Relaycast:`, err?.message ?? err);
+                    return null;
+                });
+                // Keep the agent online in the dashboard while it's working
+                if (agentClient) {
+                    stopHeartbeat = this.startRelaycastHeartbeat(agentClient);
+                }
+            }
+            // Invite the spawned agent to the workflow channel
+            if (this.channel && this.relayApiKey) {
+                const channelAgent = await this.ensureRelaycastRunnerAgent().catch(() => null);
+                await channelAgent?.channels.invite(this.channel, agent.name).catch(() => { });
+            }
+            // Post assignment notification (no task content — task arrives via direct broker injection)
+            this.postToChannel(`**[${step.name}]** Assigned to \`${agent.name}\``);
+            // Register agent handle for hub-mediated nudging
+            this.activeAgentHandles.set(agentName, agent);
+            // Wait for agent to exit, with idle nudging if configured
+            exitResult = await this.waitForExitWithIdleNudging(agent, agentDef, step, timeoutMs);
+            // Stop heartbeat now that agent has exited
+            stopHeartbeat?.();
+            if (exitResult === 'timeout') {
+                // Safety net: check if the verification file exists before giving up.
+                // The agent may have completed work but failed to /exit.
+                if (step.verification?.type === 'file_exists') {
+                    const verifyPath = path.resolve(this.cwd, step.verification.value);
+                    if (existsSync(verifyPath)) {
+                        this.postToChannel(`**[${step.name}]** Agent idle after completing work — releasing`);
+                        await agent.release();
+                        // Fall through to read output below
+                    }
+                    else {
+                        await agent.release();
+                        throw new Error(`Step "${step.name}" timed out after ${timeoutMs ?? 'unknown'}ms`);
+                    }
+                }
+                else {
+                    await agent.release();
+                    throw new Error(`Step "${step.name}" timed out after ${timeoutMs ?? 'unknown'}ms`);
+                }
+            }
+        }
+        finally {
+            // Snapshot PTY chunks before cleanup — we need them for output reading below
+            ptyChunks = this.ptyOutputBuffers.get(agentName) ?? [];
+            // Always clean up PTY resources — prevents fd leaks if spawnPty or waitForExit throws
+            stopHeartbeat?.();
+            this.activeAgentHandles.delete(agentName);
+            this.ptyOutputBuffers.delete(agentName);
+            this.ptyListeners.delete(agentName);
+            const stream = this.ptyLogStreams.get(agentName);
+            if (stream) {
+                stream.end();
+                this.ptyLogStreams.delete(agentName);
+            }
+            this.unregisterWorker(agentName);
+        }
+        let output;
+        if (ptyChunks.length > 0) {
+            output = ptyChunks.join('');
+        }
+        else {
+            // Legacy fallback: summary file
+            const summaryPath = path.join(this.summaryDir, `${step.name}.md`);
+            output = existsSync(summaryPath)
+                ? await readFile(summaryPath, 'utf-8')
+                : exitResult === 'timeout'
+                    ? 'Agent completed (released after idle timeout)'
+                    : exitResult === 'released'
+                        ? 'Agent completed (force-released after idle nudging)'
+                        : `Agent exited (${exitResult})`;
+        }
+        return output;
+    }
+    // ── Idle nudging ────────────────────────────────────────────────────────
+    /** Patterns where a hub agent coordinates spoke agents. */
+    static HUB_PATTERNS = new Set([
+        'fan-out',
+        'hub-spoke',
+        'hierarchical',
+        'map-reduce',
+        'scatter-gather',
+        'supervisor',
+        'saga',
+        'auction',
+    ]);
+    /** Roles that indicate a coordinator/lead agent (eligible for delegation guidance). */
+    static HUB_ROLES = new Set([
+        'lead',
+        'hub',
+        'coordinator',
+        'supervisor',
+        'orchestrator',
+        'auctioneer',
+    ]);
+    /**
+     * Wait for agent exit with idle detection and nudging.
+     * If no idle nudge config is set, falls through to simple waitForExit.
+     */
+    async waitForExitWithIdleNudging(agent, agentDef, step, timeoutMs) {
+        const nudgeConfig = this.currentConfig?.swarm.idleNudge;
+        if (!nudgeConfig) {
+            // No nudge config — backward compatible simple wait
+            return agent.waitForExit(timeoutMs);
+        }
+        const nudgeAfterMs = nudgeConfig.nudgeAfterMs ?? 120_000;
+        const escalateAfterMs = nudgeConfig.escalateAfterMs ?? 120_000;
+        const maxNudges = nudgeConfig.maxNudges ?? 1;
+        let nudgeCount = 0;
+        const startTime = Date.now();
+        while (true) {
+            // Calculate remaining time from overall timeout
+            const elapsed = Date.now() - startTime;
+            const remaining = timeoutMs ? timeoutMs - elapsed : undefined;
+            if (remaining !== undefined && remaining <= 0) {
+                return 'timeout';
+            }
+            // nudgeAfterMs = how long to wait before nudging (first interval).
+            // escalateAfterMs = how long to wait between subsequent nudges.
+            //
+            // We wait for exit, not for idle. The broker's idle_threshold_secs is
+            // only 30s by default, so racing waitForExit vs waitForIdle would nudge
+            // after 30s of PTY silence regardless of nudgeAfterMs. Instead, we give
+            // the agent the full nudgeAfterMs window to finish before nudging.
+            const windowMs = nudgeCount === 0 ? nudgeAfterMs : escalateAfterMs;
+            const waitMs = remaining !== undefined ? Math.min(windowMs, remaining) : windowMs;
+            const exitResult = await agent.waitForExit(waitMs);
+            if (exitResult !== 'timeout') {
+                // Agent actually exited or was released — done
+                return exitResult;
+            }
+            // Agent is still running after the window expired.
+            if (remaining !== undefined && Date.now() - startTime >= remaining) {
+                return 'timeout';
+            }
+            // Nudge if we haven't exhausted the limit
+            if (nudgeCount < maxNudges) {
+                await this.nudgeIdleAgent(agent, agentDef, step);
+                nudgeCount++;
+                this.postToChannel(`**[${step.name}]** Agent \`${agent.name}\` idle — nudge #${nudgeCount} sent`);
+                this.emit({ type: 'step:nudged', runId: this.currentRunId ?? '', stepName: step.name, nudgeCount });
+                continue;
+            }
+            // 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();
+            return 'released';
+        }
+    }
+    /**
+     * Send a nudge to an idle agent. Uses hub-mediated nudge for hub patterns,
+     * or direct system injection otherwise.
+     */
+    async nudgeIdleAgent(agent, agentDef, step) {
+        const hubAgent = this.resolveHubForNudge(agentDef);
+        if (hubAgent) {
+            // Hub-mediated: tell the hub to check on the idle agent
+            try {
+                await hubAgent.sendMessage({
+                    to: agent.name,
+                    text: `Agent ${agent.name} appears idle on step "${step.name}". Check on them and remind them to /exit when done.`,
+                });
+                return; // Hub nudge succeeded
+            }
+            catch {
+                // Fall through to direct nudge
+            }
+        }
+        // Direct system injection via human handle
+        if (this.relay) {
+            const human = this.relay.human({ name: 'workflow-runner' });
+            await human
+                .sendMessage({
+                to: agent.name,
+                text: "You appear idle. If you've completed your task, output /exit. If still working, continue.",
+            })
+                .catch(() => {
+                // Non-critical — don't break workflow
+            });
+        }
+    }
+    /**
+     * Find the hub agent for hub-mediated nudging.
+     * Returns the hub's live Agent handle if this is a hub pattern and the idle agent is not the hub.
+     */
+    resolveHubForNudge(idleAgentDef) {
+        const pattern = this.currentConfig?.swarm.pattern;
+        if (!pattern || !WorkflowRunner.HUB_PATTERNS.has(pattern)) {
+            return undefined;
+        }
+        // Find an interactive agent with a hub-like role
+        const agents = this.currentConfig?.agents ?? [];
+        for (const agentDef of agents) {
+            // Skip non-interactive and the idle agent itself
+            if (agentDef.interactive === false)
+                continue;
+            if (agentDef.name === idleAgentDef.name)
+                continue;
+            const role = agentDef.role?.toLowerCase() ?? '';
+            const nameLC = agentDef.name.toLowerCase();
+            if (WorkflowRunner.HUB_ROLES.has(nameLC) ||
+                [...WorkflowRunner.HUB_ROLES].some((r) => role.includes(r))) {
+                // Found a hub candidate — check if we have a live handle
+                const handle = this.activeAgentHandles.get(agentDef.name);
+                if (handle)
+                    return handle;
+            }
+        }
+        return undefined;
+    }
+    // ── Verification ────────────────────────────────────────────────────────
+    runVerification(check, output, stepName, injectedTaskText) {
+        switch (check.type) {
+            case 'output_contains': {
+                // Guard against false positives: the PTY captures the injected task text
+                // verbatim, so if the verification token appears in the task itself the
+                // check would pass immediately without the agent doing any real work.
+                // When the task contains the token, require a SECOND occurrence — one
+                // from the task injection and one from the agent's actual response.
+                const token = check.value;
+                const taskHasToken = injectedTaskText ? injectedTaskText.includes(token) : false;
+                if (taskHasToken) {
+                    const first = output.indexOf(token);
+                    const hasSecond = first !== -1 && output.includes(token, first + token.length);
+                    if (!hasSecond) {
+                        throw new Error(`Verification failed for "${stepName}": output does not contain "${token}" ` +
+                            `(token found only in task injection — agent must output it explicitly)`);
+                    }
+                }
+                else if (!output.includes(token)) {
+                    throw new Error(`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))) {
+                    throw new Error(`Verification failed for "${stepName}": file "${check.value}" does not exist`);
+                }
+                break;
+            case 'custom':
+                // Custom verifications are evaluated by callers; no-op here
+                break;
+        }
+    }
+    // ── State helpers ─────────────────────────────────────────────────────
+    async updateRunStatus(runId, status, error) {
+        const patch = {
+            status,
+            updatedAt: new Date().toISOString(),
+        };
+        if (status === 'completed' || status === 'failed' || status === 'cancelled') {
+            patch.completedAt = new Date().toISOString();
+        }
+        if (error) {
+            patch.error = error;
+        }
+        await this.db.updateRun(runId, patch);
+    }
+    async markStepFailed(state, error, runId) {
+        state.row.status = 'failed';
+        state.row.error = error;
+        state.row.completedAt = new Date().toISOString();
+        await this.db.updateStep(state.row.id, {
+            status: 'failed',
+            error,
+            completedAt: state.row.completedAt,
+            updatedAt: new Date().toISOString(),
+        });
+        this.emit({ type: 'step:failed', runId, stepName: state.row.stepName, error });
+    }
+    async markDownstreamSkipped(failedStepName, allSteps, stepStates, runId) {
+        const queue = [failedStepName];
+        const visited = new Set();
+        while (queue.length > 0) {
+            const current = queue.shift();
+            if (visited.has(current))
+                continue;
+            visited.add(current);
+            for (const step of allSteps) {
+                if (step.dependsOn?.includes(current)) {
+                    const state = stepStates.get(step.name);
+                    if (state && state.row.status === 'pending') {
+                        state.row.status = 'skipped';
+                        await this.db.updateStep(state.row.id, {
+                            status: 'skipped',
+                            updatedAt: new Date().toISOString(),
+                        });
+                        this.emit({ type: 'step:skipped', runId, stepName: step.name });
+                        this.postToChannel(`**[${step.name}]** Skipped — upstream dependency "${current}" failed`);
+                        await this.trajectory?.stepSkipped(step, `Upstream dependency "${current}" failed`);
+                        await this.trajectory?.decide(`Whether to skip ${step.name}`, 'skip', `Upstream dependency "${current}" failed`);
+                        queue.push(step.name);
+                    }
+                }
+            }
+        }
+    }
+    // ── Control flow helpers ──────────────────────────────────────────────
+    checkAborted() {
+        if (this.abortController?.signal.aborted) {
+            throw new Error('Workflow aborted');
+        }
+    }
+    async waitIfPaused() {
+        if (!this.paused)
+            return;
+        await new Promise((resolve) => {
+            this.pauseResolver = resolve;
+        });
+    }
+    delay(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    // ── Channel messaging ──────────────────────────────────────────────────
+    /**
+     * Build a metadata note about non-interactive workers for inclusion in interactive agent tasks.
+     * 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.');
+    }
+    /**
+     * Build guidance that encourages agents to autonomously delegate subtasks
+     * to helper agents when work is too complex for a single pass.
+     */
+    /**
+     * Returns a relay registration preamble for CLIs that don't auto-call
+     * `register` via the MCP system prompt (everyone except claude).
+     *
+     * Claude reads the Relaycast system prompt and registers on its own.
+     * Codex, gemini, etc. have the MCP server configured with the workspace
+     * 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 (relay_send, relay_inbox, post_message, 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.`);
+    }
+    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' +
+            '  - relay_spawn(name="helper-1", cli="claude", task="Specific subtask description")\n' +
+            '  - Coordinate via relay_send(to="helper-1", message="...")\n' +
+            '  - Check on them with relay_inbox()\n' +
+            '  - Clean up when done: relay_release(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."');
+    }
+    /** Post a message to the workflow channel. Fire-and-forget — never throws or blocks. */
+    postToChannel(text) {
+        if (!this.relayApiKey || !this.channel)
+            return;
+        this.ensureRelaycastRunnerAgent()
+            .then((agent) => agent.send(this.channel, text))
+            .catch(() => {
+            // Non-critical — don't break workflow execution
+        });
+    }
+    /** 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'));
+    }
+    /** 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'));
+    }
+    /**
+     * Log a human-readable run summary to the console after completion or failure.
+     * Extracts the last meaningful lines from each step's raw PTY output.
+     */
+    logRunSummary(workflowName, outcomes, runId) {
+        const completed = outcomes.filter((o) => o.status === 'completed');
+        const failed = outcomes.filter((o) => o.status === 'failed');
+        const skipped = outcomes.filter((o) => o.status === 'skipped');
+        console.log('');
+        console.log('━'.repeat(70));
+        console.log(`  Workflow "${workflowName}" — ${failed.length === 0 ? 'COMPLETED' : 'FAILED'}`);
+        console.log(`  ${completed.length} passed, ${failed.length} failed, ${skipped.length} skipped`);
+        console.log('━'.repeat(70));
+        for (const outcome of outcomes) {
+            const icon = outcome.status === 'completed' ? '✓' : outcome.status === 'failed' ? '✗' : '⊘';
+            const retryNote = outcome.attempts > 1 ? ` (${outcome.attempts} attempts)` : '';
+            console.log(`  ${icon} ${outcome.name} [${outcome.agent}]${retryNote}`);
+            if (outcome.error) {
+                console.log(`    Error: ${outcome.error}`);
+            }
+            // Extract last meaningful lines from raw PTY output
+            if (outcome.output) {
+                const excerpt = this.extractOutputExcerpt(outcome.output);
+                if (excerpt) {
+                    for (const line of excerpt.split('\n')) {
+                        console.log(`    ${line}`);
+                    }
+                }
+            }
+        }
+        // Point to detailed output files
+        const outputDir = this.getStepOutputDir(runId);
+        const logsDir = path.join(this.cwd, '.agent-relay', 'team', 'worker-logs');
+        console.log('');
+        console.log(`  Step output: ${outputDir}`);
+        console.log(`  Agent logs:  ${logsDir}`);
+        console.log('━'.repeat(70));
+        console.log('');
+    }
+    /**
+     * Extract a useful excerpt from raw PTY output.
+     * Looks for the agent's final text output (ignoring ANSI, system prompts, tool calls).
+     */
+    extractOutputExcerpt(rawOutput) {
+        const stripped = WorkflowRunner.stripAnsi(rawOutput);
+        // Split into lines, filter out noise
+        const lines = stripped.split('\n').filter((line) => {
+            const trimmed = line.trim();
+            if (!trimmed)
+                return false;
+            // Skip system/UI chrome
+            if (trimmed.startsWith('╭') || trimmed.startsWith('╰') || trimmed.startsWith('│'))
+                return false;
+            if (trimmed.startsWith('─'))
+                return false;
+            if (trimmed.startsWith('❯') || trimmed.startsWith('⏵'))
+                return false;
+            if (trimmed.startsWith('<system-reminder>') || trimmed.startsWith('</system-reminder>'))
+                return false;
+            if (/^\[?workflow\s/.test(trimmed))
+                return false;
+            // Skip tool invocations
+            if (/^(Read|Edit|Bash|Glob|Grep|Task|Explore|Write)\(/.test(trimmed))
+                return false;
+            // Skip thinking indicators
+            if (/^[·✳✻✽⏺]?\s*Sublimating/.test(trimmed))
+                return false;
+            // Skip very short lines (likely UI fragments)
+            if (trimmed.length < 10)
+                return false;
+            return true;
+        });
+        if (lines.length === 0)
+            return '';
+        // Take the last few meaningful lines (agent's final words)
+        const tail = lines.slice(-5);
+        const excerpt = tail.map((l) => l.trim().slice(0, 120)).join('\n');
+        return excerpt.length > 0 ? `...\n${excerpt}` : '';
+    }
+    // ── Trajectory helpers ────────────────────────────────────────────────
+    /** Analyze DAG structure for trajectory context. */
+    analyzeDAG(steps) {
+        const roots = steps.filter((s) => !s.dependsOn?.length);
+        const withDeps = steps.filter((s) => s.dependsOn?.length);
+        const parts = [`Parsed ${steps.length} steps`];
+        if (roots.length > 1) {
+            parts.push(`${roots.length} parallel tracks`);
+        }
+        if (withDeps.length > 0) {
+            parts.push(`${withDeps.length} dependent steps`);
+        }
+        parts.push('DAG validated, no cycles');
+        return parts.join(', ');
+    }
+    /** Collect step outcomes for trajectory synthesis. */
+    collectOutcomes(stepStates, steps) {
+        const stepsWithVerification = new Set(steps?.filter((s) => s.verification).map((s) => s.name) ?? []);
+        const outcomes = [];
+        for (const [name, state] of stepStates) {
+            outcomes.push({
+                name,
+                agent: state.row.agentName ?? 'deterministic',
+                status: state.row.status === 'completed'
+                    ? 'completed'
+                    : state.row.status === 'skipped'
+                        ? 'skipped'
+                        : 'failed',
+                attempts: state.row.retryCount + 1,
+                output: state.row.output,
+                error: state.row.error,
+                verificationPassed: state.row.status === 'completed' && stepsWithVerification.has(name),
+            });
+        }
+        return outcomes;
+    }
+    // ── ID generation ─────────────────────────────────────────────────────
+    generateId() {
+        return randomBytes(12).toString('hex');
+    }
+    generateShortId() {
+        return randomBytes(4).toString('hex');
+    }
+    /** Strip ANSI escape codes from terminal output — delegates to pty.ts canonical regex. */
+    static stripAnsi(text) {
+        return stripAnsiFn(text);
+    }
+    /**
+     * Strip TUI chrome from PTY-captured output before posting to a channel.
+     * Removes: ANSI codes, unicode spinner/thinking characters, cursor-movement
+     * artifacts, and collapses runs of blank lines to a single blank line.
+     * The raw (ANSI-stripped) output is still written to disk for step chaining.
+     */
+    static scrubForChannel(text) {
+        // Strip system-reminder blocks (closed or unclosed)
+        const withoutSystemReminders = text
+            .replace(/<system-reminder>[\s\S]*?<\/system-reminder>/giu, '')
+            .replace(/<system-reminder>[\s\S]*/giu, '');
+        // Normalize CRLF and bare \r before stripping ANSI — PTY output often
+        // contains \r\r\n which leaves stray \r after stripping that confuse line splitting.
+        const normalized = withoutSystemReminders.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+        const ansiStripped = stripAnsiFn(normalized);
+        // Unicode spinner / ornament characters used by Claude TUI animations.
+        // Includes block-element chars (▗▖▘▝) used in the Claude Code header bar.
+        const SPINNER = '\\u2756\\u2738\\u2739\\u273a\\u273b\\u273c\\u273d\\u2731\\u2732\\u2733\\u2734\\u2735\\u2736\\u2737\\u2743\\u2745\\u2746\\u25d6\\u25d7\\u25d8\\u25d9\\u2022\\u25cf\\u25cb\\u25a0\\u25a1\\u25b6\\u25c0\\u23f5\\u23f6\\u23f7\\u23f8\\u23f9\\u25e2\\u25e3\\u25e4\\u25e5\\u2597\\u2596\\u2598\\u259d\\u2bc8\\u2bc7\\u2bc5\\u2bc6\\u00b7' +
+            '\\u2590\\u258c\\u2588\\u2584\\u2580\\u259a\\u259e'; // additional block elements
+        const spinnerRe = new RegExp(`[${SPINNER}]`, 'gu');
+        const spinnerClassRe = new RegExp(`^[\\s${SPINNER}]*$`, 'u');
+        // Line-level filters
+        const boxDrawingOnlyRe = /^[\s\u2500-\u257f\u2580-\u259f\u25a0-\u25ff\-_=~]{3,}$/u;
+        // Broker internal log lines: "2026-02-26T12:45:12.123Z  INFO agent_relay_broker::..."
+        const brokerLogRe = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d+Z\s+(?:INFO|WARN|ERROR|DEBUG)\s/u;
+        const claudeHeaderRe = /^(?:[\s\u2580-\u259f✢*·▗▖▘▝]+\s*)?(?:Claude\s+Code(?:\s+v?[\d.]+)?|(?:Sonnet|Haiku|Opus)\s*[\d.]+|claude-(?:sonnet|haiku|opus)-[\w.-]+|Running\s+on\s+claude)/iu;
+        // TUI directory breadcrumb lines (e.g. "  ~/Projects/agent-workforce/relay-...")
+        const dirBreadcrumbRe = /^\s*~[\\/]/u;
+        const uiHintRe = /\b(?:Press\s+up\s+to\s+edit|tab\s+to\s+queue|bypass\s+permissions|esc\s+to\s+interrupt)\b/iu;
+        // Any spinner-prefixed word ending in … — catches all Claude thinking animations
+        // regardless of the specific word used (Thinking, Cascading, Flibbertigibbeting, etc.)
+        const thinkingLineRe = new RegExp(`^[\\s${SPINNER}]*\\s*\\w[\\w\\s]*\\u2026\\s*$`, 'u');
+        const cursorOnlyRe = /^[\s❯⎿›»◀▶←→↑↓⟨⟩⟪⟫·]+$/u;
+        const slashCommandRe = /^\/\w+\s*$/u;
+        const mcpJsonKvRe = /^\s*"(?:type|method|params|result|id|jsonrpc|tool|name|arguments|content|role|metadata)"\s*:/u;
+        const meaningfulContentRe = /[a-zA-Z0-9]/u;
+        const countJsonDepth = (line) => {
+            let depth = 0;
+            for (const ch of line) {
+                if (ch === '{' || ch === '[')
+                    depth += 1;
+                if (ch === '}' || ch === ']')
+                    depth -= 1;
+            }
+            return depth;
+        };
+        const lines = ansiStripped.split('\n');
+        const meaningful = [];
+        let jsonDepth = 0;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (jsonDepth > 0) {
+                jsonDepth += countJsonDepth(line);
+                if (jsonDepth <= 0)
+                    jsonDepth = 0;
+                continue;
+            }
+            if (trimmed.length === 0)
+                continue;
+            if (trimmed.startsWith('{') || /^\[\s*\{/.test(trimmed)) {
+                jsonDepth = Math.max(countJsonDepth(line), 0);
+                continue;
+            }
+            if (mcpJsonKvRe.test(line))
+                continue;
+            if (spinnerClassRe.test(trimmed))
+                continue;
+            if (boxDrawingOnlyRe.test(trimmed))
+                continue;
+            if (brokerLogRe.test(trimmed))
+                continue;
+            if (claudeHeaderRe.test(trimmed))
+                continue;
+            if (dirBreadcrumbRe.test(trimmed))
+                continue;
+            if (uiHintRe.test(trimmed))
+                continue;
+            if (thinkingLineRe.test(trimmed))
+                continue;
+            if (cursorOnlyRe.test(trimmed))
+                continue;
+            if (slashCommandRe.test(trimmed))
+                continue;
+            if (!meaningfulContentRe.test(trimmed))
+                continue;
+            // Drop TUI animation frame fragments: lines where stripping spinners and
+            // whitespace leaves ≤ 3 alphanumeric characters (e.g. "F", "l  b", "i  g").
+            const alphanum = trimmed.replace(spinnerRe, '').replace(/\s+/g, '');
+            if (alphanum.replace(/[^a-zA-Z0-9]/g, '').length <= 3)
+                continue;
+            meaningful.push(line);
+        }
+        return meaningful
+            .join('\n')
+            .replace(/\n{3,}/g, '\n\n')
+            .trim();
+    }
+    /** Sanitize a workflow name into a valid channel name. */
+    sanitizeChannelName(name) {
+        return name
+            .toLowerCase()
+            .replace(/[^a-z0-9-]/g, '-')
+            .replace(/-+/g, '-')
+            .slice(0, 32);
+    }
+    /** Directory for persisted step outputs: .agent-relay/step-outputs/{runId}/ */
+    getStepOutputDir(runId) {
+        return path.join(this.cwd, '.agent-relay', 'step-outputs', runId);
+    }
+    /** Persist step output to disk and post full output as a channel message. */
+    async persistStepOutput(runId, stepName, output) {
+        // 1. Write to disk
+        try {
+            const dir = this.getStepOutputDir(runId);
+            mkdirSync(dir, { recursive: true });
+            const cleaned = WorkflowRunner.stripAnsi(output);
+            await writeFile(path.join(dir, `${stepName}.md`), cleaned);
+        }
+        catch {
+            // Non-critical
+        }
+        // 2. Post scrubbed output as a single channel message (most recent tail only)
+        const scrubbed = WorkflowRunner.scrubForChannel(output);
+        if (scrubbed.length === 0) {
+            this.postToChannel(`**[${stepName}]** Step completed — output written to disk`);
+            return;
+        }
+        const maxMsg = 2000;
+        const preview = scrubbed.length > maxMsg ? scrubbed.slice(-maxMsg) : scrubbed;
+        this.postToChannel(`**[${stepName}] Output:**\n\`\`\`\n${preview}\n\`\`\``);
+    }
+    /** Load persisted step output from disk. */
+    loadStepOutput(runId, stepName) {
+        try {
+            const filePath = path.join(this.getStepOutputDir(runId), `${stepName}.md`);
+            if (!existsSync(filePath))
+                return undefined;
+            return readFileSync(filePath, 'utf-8');
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Get or create the worker logs directory (.agent-relay/team/worker-logs) */
+    getWorkerLogsDir() {
+        const logsDir = path.join(this.cwd, '.agent-relay', 'team', 'worker-logs');
+        mkdirSync(logsDir, { recursive: true });
+        return logsDir;
+    }
+    /** Register a spawned agent in workers.json so `agents:kill` can find it. */
+    registerWorker(agentName, cli, task, pid, interactive = true) {
+        // Track in memory first (no race condition)
+        const workerEntry = {
+            cli,
+            task: task.slice(0, 500),
+            spawnedAt: Date.now(),
+            pid,
+            interactive,
+            logFile: path.join(this.getWorkerLogsDir(), `${agentName}.log`),
+        };
+        this.activeWorkers.set(agentName, workerEntry);
+        // Serialize file writes with mutex to prevent race conditions
+        this.workersFileLock = this.workersFileLock.then(() => {
+            try {
+                mkdirSync(path.dirname(this.workersPath), { recursive: true });
+                // Filter out any existing entry with the same name before adding
+                const existing = this.readWorkers().filter((w) => w.name !== agentName);
+                existing.push({ name: agentName, ...workerEntry });
+                this.writeWorkers(existing);
+            }
+            catch {
+                // Non-critical — don't fail the workflow if workers.json can't be written
+            }
+        });
+    }
+    /** Remove a spawned agent from workers.json after it exits. */
+    unregisterWorker(agentName) {
+        // Remove from in-memory tracking first
+        this.activeWorkers.delete(agentName);
+        // Serialize file writes with mutex to prevent race conditions
+        this.workersFileLock = this.workersFileLock.then(() => {
+            try {
+                const existing = this.readWorkers();
+                const filtered = existing.filter((w) => w.name !== agentName);
+                this.writeWorkers(filtered);
+            }
+            catch {
+                // Non-critical
+            }
+        });
+    }
+    readWorkers() {
+        try {
+            if (!existsSync(this.workersPath))
+                return [];
+            const raw = JSON.parse(readFileSync(this.workersPath, 'utf-8'));
+            return Array.isArray(raw?.workers) ? raw.workers : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    writeWorkers(workers) {
+        writeFileSync(this.workersPath, JSON.stringify({ workers }, null, 2));
+    }
+}
+//# sourceMappingURL=runner.js.map