chainlesschain 0.162.70 → 0.162.72

package/src/lib/cowork-workflow.js

@@ -36,6 +36,9 @@ import { evaluate as evalExpr, resolveReference } from "./workflow-expr.js";
 /** Maximum number of items a single forEach step can expand into. */
 export const MAX_FAN_OUT = 500;
 
+/** Absolute ceiling on a single loop step's iterations (infinite-loop guard). */
+export const MAX_LOOP_ITERATIONS = 100;
+
 export const _deps = {
   existsSync,
   mkdirSync,
@@ -46,6 +49,10 @@ export const _deps = {
   appendFileSync,
   now: () => Date.now(),
   runTask: null, // injected by CLI
+  // Timer seams (injectable for deterministic retry/timeout tests).
+  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  setTimeout: (fn, ms) => setTimeout(fn, ms),
+  clearTimeout: (t) => clearTimeout(t),
 };
 
 // ─── Paths ───────────────────────────────────────────────────────────────────
@@ -104,6 +111,61 @@ export function validateWorkflow(wf) {
           );
         }
       }
+      if (
+        s.retries !== undefined &&
+        (typeof s.retries !== "number" ||
+          !Number.isInteger(s.retries) ||
+          s.retries < 0)
+      ) {
+        errors.push(`steps[${i}].retries must be a non-negative integer`);
+      }
+      if (
+        s.timeoutMs !== undefined &&
+        (typeof s.timeoutMs !== "number" ||
+          !Number.isFinite(s.timeoutMs) ||
+          s.timeoutMs <= 0)
+      ) {
+        errors.push(`steps[${i}].timeoutMs must be a positive number`);
+      }
+      if (
+        s.retryDelayMs !== undefined &&
+        (typeof s.retryDelayMs !== "number" ||
+          !Number.isFinite(s.retryDelayMs) ||
+          s.retryDelayMs < 0)
+      ) {
+        errors.push(`steps[${i}].retryDelayMs must be a non-negative number`);
+      }
+      if (
+        s.retryBackoff !== undefined &&
+        s.retryBackoff !== "fixed" &&
+        s.retryBackoff !== "exponential"
+      ) {
+        errors.push(
+          `steps[${i}].retryBackoff must be "fixed" or "exponential"`,
+        );
+      }
+      const hasWhile = s.loopWhile !== undefined;
+      const hasUntil = s.loopUntil !== undefined;
+      if (hasWhile && typeof s.loopWhile !== "string") {
+        errors.push(`steps[${i}].loopWhile must be a string expression`);
+      }
+      if (hasUntil && typeof s.loopUntil !== "string") {
+        errors.push(`steps[${i}].loopUntil must be a string expression`);
+      }
+      if (hasWhile && hasUntil) {
+        errors.push(`steps[${i}] cannot set both loopWhile and loopUntil`);
+      }
+      if ((hasWhile || hasUntil) && s.forEach !== undefined) {
+        errors.push(`steps[${i}] cannot combine a loop with forEach`);
+      }
+      if (
+        s.maxIterations !== undefined &&
+        (typeof s.maxIterations !== "number" ||
+          !Number.isInteger(s.maxIterations) ||
+          s.maxIterations <= 0)
+      ) {
+        errors.push(`steps[${i}].maxIterations must be a positive integer`);
+      }
     }
     // Check dependsOn references exist
     for (const s of wf.steps) {
@@ -329,17 +391,467 @@ export function removeWorkflow(cwd, id) {
   return true;
 }
 
+// ─── Per-step retry / timeout ─────────────────────────────────────────────────
+
+/**
+ * Compute the delay (ms) to wait BEFORE a retry, given the just-failed attempt
+ * number (1-based). `fixed` returns `retryDelayMs` verbatim; `exponential`
+ * doubles it per prior attempt (delay = base · 2^(attempt-1)).
+ */
+export function retryDelayFor(step, attempt) {
+  const base = Number(step.retryDelayMs) || 0;
+  if (base <= 0) return 0;
+  if (step.retryBackoff === "exponential") {
+    return base * Math.pow(2, attempt - 1);
+  }
+  return base;
+}
+
+/**
+ * Race a promise (produced by `factory`) against a per-attempt timeout.
+ * Resolves/rejects with the promise when it settles first; rejects with a
+ * "timed out" error if the timer fires first. The timer is always cleared, and
+ * a late rejection from the losing promise is swallowed to avoid an unhandled
+ * rejection (the underlying task is best-effort abandoned — runTask has no
+ * cancellation contract).
+ */
+export async function withTimeout(factory, timeoutMs) {
+  if (!timeoutMs || timeoutMs <= 0) return factory();
+  const p = Promise.resolve().then(factory);
+  let timer = null;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = _deps.setTimeout(() => {
+      reject(new Error(`step timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+  try {
+    return await Promise.race([p, timeout]);
+  } finally {
+    if (timer != null) _deps.clearTimeout(timer);
+    p.catch(() => {}); // guard a late rejection from the abandoned task
+  }
+}
+
+/**
+ * Run one step's task with optional `timeoutMs` and `retries` (with `fixed` or
+ * `exponential` `retryDelayMs` backoff). An attempt counts as a failure if the
+ * task throws, times out, or returns a non-`completed` status. Returns
+ * `{ ok, entry?, error?, attempts }`. `attempts` is the total number of tries.
+ */
+export async function runStepWithRetry({ step, message, cwd, llmOptions }) {
+  const maxRetries = Math.max(0, Math.floor(Number(step.retries) || 0));
+  const timeoutMs = Number(step.timeoutMs) || 0;
+  let lastEntry = null;
+  let lastErr = null;
+  for (let attempt = 1; attempt <= maxRetries + 1; attempt++) {
+    try {
+      const entry = await withTimeout(
+        () =>
+          _deps.runTask({
+            templateId: step.templateId || null,
+            userMessage: message,
+            files: step.files || [],
+            cwd,
+            llmOptions,
+          }),
+        timeoutMs,
+      );
+      if (entry && entry.status === "completed") {
+        return { ok: true, entry, attempts: attempt };
+      }
+      lastEntry = entry; // ran but not completed → retry-eligible
+      lastErr = null;
+    } catch (err) {
+      lastErr = err; // threw or timed out → retry-eligible
+      lastEntry = null;
+    }
+    if (attempt <= maxRetries) {
+      const delay = retryDelayFor(step, attempt);
+      if (delay > 0) await _deps.sleep(delay);
+    }
+  }
+  const attempts = maxRetries + 1;
+  if (lastEntry) return { ok: false, entry: lastEntry, attempts };
+  return { ok: false, error: lastErr, attempts };
+}
+
+/** Attach an `attempts` field only when more than one try occurred (keeps the
+ * single-attempt result shape byte-identical to the pre-retry behavior). */
+function _withAttempts(result, attempts) {
+  if (attempts > 1) return { ...(result || {}), attempts };
+  return result;
+}
+
+/** Build a single-step outcome object from a `runStepWithRetry` result. */
+function outcomeFromRetry(recordId, r) {
+  if (r.ok || r.entry) {
+    return {
+      id: recordId,
+      status: r.entry.status,
+      taskId: r.entry.taskId,
+      result: _withAttempts(r.entry.result, r.attempts),
+    };
+  }
+  return {
+    id: recordId,
+    status: "failed",
+    taskId: null,
+    result: _withAttempts(
+      { summary: `Step threw: ${r.error.message}` },
+      r.attempts,
+    ),
+  };
+}
+
+// ─── while / until loop nodes ──────────────────────────────────────────────────
+
+/** True when a step is a loop node (`loopWhile` or `loopUntil`). */
+export function isLoopStep(step) {
+  return step.loopWhile !== undefined || step.loopUntil !== undefined;
+}
+
+/** Resolve a loop step's iteration cap, clamped to MAX_LOOP_ITERATIONS. */
+export function loopIterationCap(step) {
+  const m = Number(step.maxIterations);
+  if (Number.isFinite(m) && m > 0) {
+    return Math.min(Math.floor(m), MAX_LOOP_ITERATIONS);
+  }
+  return MAX_LOOP_ITERATIONS;
+}
+
+/**
+ * Substitute loop-local tokens in a message template: `${iter}` → the 1-based
+ * iteration number, `${self.<field>}` → the step's own most-recent iteration
+ * result (empty on the first iteration). Other `${step.<id>.<field>}` tokens
+ * are left for `substitutePlaceholders`.
+ */
+export function substituteLoopVars(template, { stepId, iter, resultsById }) {
+  if (typeof template !== "string") return template;
+  let out = template.replace(/\$\{iter\}/g, String(iter));
+  out = out.replace(/\$\{self\.([\w-]+)\}/g, (_, field) => {
+    const entry = resultsById?.get?.(stepId);
+    if (!entry) return "";
+    if (field === "summary") return entry.result?.summary ?? "";
+    if (field === "status") return entry.status ?? "";
+    if (field === "taskId") return entry.taskId ?? "";
+    if (field === "iterations") return String(entry.result?.iterations ?? 0);
+    if (field === "tokenCount") return String(entry.result?.tokenCount ?? 0);
+    const v = entry.result?.[field];
+    return v == null ? "" : String(v);
+  });
+  return out;
+}
+
+/**
+ * Evaluate whether a loop step should run another iteration (post-test). The
+ * condition may reference `${self.<field>}` (the just-stored iteration result)
+ * and `${iter}`. `loopWhile` continues while the expression is true; `loopUntil`
+ * continues until it becomes true. Throws on a malformed expression.
+ */
+export function evalLoopContinue(step, { stepId, iter, resultsById }) {
+  const isWhile = step.loopWhile !== undefined;
+  const expr = isWhile ? step.loopWhile : step.loopUntil;
+  const subst = String(expr)
+    .replace(/\$\{iter\}/g, String(iter))
+    .replace(/\$\{self\.([\w-]+)\}/g, (_, f) => `\${step.${stepId}.${f}}`);
+  const val = evalExpr(subst, { step: resultsById });
+  return isWhile ? val === true : val !== true;
+}
+
+/**
+ * Run a loop step: repeat its task until the `loopWhile`/`loopUntil` condition
+ * says to stop, a failing iteration aborts it, or the iteration cap is hit.
+ * Each iteration inherits the step's retry/timeout config. The final result
+ * carries `iterations`, `loopExhausted`, and `loopStop` (`condition`|`cap`|
+ * `failed`|`bad-condition`).
+ */
+export async function runLoopStep({
+  step,
+  recordId,
+  cwd,
+  llmOptions,
+  resultsById,
+}) {
+  const cap = loopIterationCap(step);
+  let last = null;
+  let iterations = 0;
+  let stopReason = "cap";
+  for (let iter = 1; iter <= cap; iter++) {
+    iterations = iter;
+    const withSelf = substituteLoopVars(step.message, {
+      stepId: recordId,
+      iter,
+      resultsById,
+    });
+    const message = substitutePlaceholders(withSelf, resultsById);
+    const r = await runStepWithRetry({ step, message, cwd, llmOptions });
+    last = outcomeFromRetry(recordId, r);
+    resultsById.set(recordId, last);
+    if (last.status === "failed") {
+      stopReason = "failed";
+      break;
+    }
+    let cont;
+    try {
+      cont = evalLoopContinue(step, { stepId: recordId, iter, resultsById });
+    } catch (err) {
+      last = {
+        id: recordId,
+        status: "failed",
+        taskId: null,
+        result: {
+          summary: `invalid loop condition on '${recordId}': ${err.message}`,
+        },
+      };
+      resultsById.set(recordId, last);
+      stopReason = "bad-condition";
+      break;
+    }
+    if (!cont) {
+      stopReason = "condition";
+      break;
+    }
+  }
+  return {
+    id: recordId,
+    status: last ? last.status : "skipped",
+    taskId: last?.taskId ?? null,
+    result: {
+      ...(last?.result || {}),
+      iterations,
+      loopExhausted: stopReason === "cap",
+      loopStop: stopReason,
+    },
+  };
+}
+
+// ─── Step node + no-barrier pipeline ──────────────────────────────────────────
+
+/**
+ * Run a single step to completion, resolving its when-gate / loop / forEach /
+ * plain task exactly as the batch executor does, and storing results (including
+ * a forEach parent aggregate) in `resultsById`. Returns `{ outcomes, failed }`:
+ * `outcomes` are the entries to add to the run's step list (forEach contributes
+ * its children, not the parent); `failed` is true when any non-skipped outcome
+ * is not "completed". Used by the no-barrier pipeline scheduler.
+ */
+export async function runStepNode(step, ctx) {
+  const { resultsById, cwd, llmOptions, onStepStart, onStepComplete } = ctx;
+  const recordId = step.id;
+  const single = (status, summary) => {
+    const o = { id: recordId, status, taskId: null, result: { summary } };
+    resultsById.set(recordId, o);
+    return {
+      outcomes: [o],
+      failed: status !== "completed" && status !== "skipped",
+    };
+  };
+
+  let runThis;
+  try {
+    runThis = shouldRunStep(step, resultsById);
+  } catch (err) {
+    return single("failed", err.message);
+  }
+  if (!runThis) return single("skipped", "when-condition false");
+
+  if (isLoopStep(step)) {
+    if (onStepStart) onStepStart({ stepId: recordId, message: step.message });
+    const o = await runLoopStep({
+      step,
+      recordId,
+      cwd,
+      llmOptions,
+      resultsById,
+    });
+    resultsById.set(recordId, o);
+    if (onStepComplete) onStepComplete(o);
+    return {
+      outcomes: [o],
+      failed: o.status !== "completed" && o.status !== "skipped",
+    };
+  }
+
+  if (step.forEach !== undefined) {
+    let items;
+    try {
+      items = resolveForEachItems(step.forEach, resultsById);
+    } catch (err) {
+      return single("failed", err.message);
+    }
+    if (items.length === 0) return single("skipped", "forEach items empty");
+    const children = await Promise.all(
+      items.map(async (item, k) => {
+        const childId = `${recordId}[${k}]`;
+        const withItem = substituteItem(step.message, item);
+        const msg = substitutePlaceholders(withItem, resultsById);
+        if (onStepStart) onStepStart({ stepId: childId, message: msg });
+        const r = await runStepWithRetry({
+          step,
+          message: msg,
+          cwd,
+          llmOptions,
+        });
+        const co = outcomeFromRetry(childId, r);
+        resultsById.set(childId, co);
+        if (onStepComplete) onStepComplete(co);
+        return co;
+      }),
+    );
+    const allOk = children.every((c) => c.status === "completed");
+    const anyOk = children.some((c) => c.status === "completed");
+    resultsById.set(recordId, {
+      id: recordId,
+      status: allOk ? "completed" : anyOk ? "partial" : "failed",
+      taskId: null,
+      result: {
+        summary: children.map((c) => c.result?.summary ?? "").join("\n"),
+        children: children.length,
+      },
+    });
+    return {
+      outcomes: children,
+      failed: children.some((c) => c.status !== "completed"),
+    };
+  }
+
+  const message = substitutePlaceholders(step.message, resultsById);
+  if (onStepStart) onStepStart({ stepId: recordId, message });
+  const r = await runStepWithRetry({ step, message, cwd, llmOptions });
+  const o = outcomeFromRetry(recordId, r);
+  resultsById.set(recordId, o);
+  if (onStepComplete) onStepComplete(o);
+  return { outcomes: [o], failed: o.status !== "completed" };
+}
+
+/**
+ * No-barrier pipeline scheduler: start each step the instant *its own*
+ * dependencies finish, rather than waiting for the whole dependency level.
+ * Up to `maxParallel` step nodes run concurrently. On failure with
+ * `continueOnError` off, no new steps are scheduled (in-flight ones finish) and
+ * the rest are marked skipped. Produces the same outcome set as the batch
+ * executor — only the wall-clock idle between levels is removed.
+ */
+export async function runPipeline({
+  steps,
+  resultsById,
+  maxParallel = 4,
+  continueOnError = false,
+  cwd,
+  llmOptions = {},
+  onStepStart,
+  onStepComplete,
+}) {
+  const limit = Math.max(1, Math.floor(maxParallel) || 1);
+  const remainingDeps = new Map(
+    steps.map((s) => [s.id, new Set(s.dependsOn || [])]),
+  );
+  const dependents = new Map(steps.map((s) => [s.id, []]));
+  for (const s of steps) {
+    for (const d of s.dependsOn || []) {
+      if (dependents.has(d)) dependents.get(d).push(s.id);
+    }
+  }
+  const scheduled = new Set();
+  const stepOutcomes = [];
+  let anyFailure = false;
+  let halted = false;
+  let active = 0;
+
+  await new Promise((resolve) => {
+    function pump() {
+      if (!halted) {
+        for (const s of steps) {
+          if (active >= limit) break;
+          if (scheduled.has(s.id)) continue;
+          if (remainingDeps.get(s.id).size !== 0) continue;
+          scheduled.add(s.id);
+          active++;
+          launch(s);
+        }
+      }
+      if (active === 0 && (halted || scheduled.size === steps.length)) {
+        for (const s of steps) {
+          if (scheduled.has(s.id)) continue;
+          const o = {
+            id: s.id,
+            status: "skipped",
+            taskId: null,
+            result: { summary: "skipped due to earlier failure" },
+          };
+          resultsById.set(s.id, o);
+          stepOutcomes.push(o);
+          scheduled.add(s.id);
+        }
+        resolve();
+      }
+    }
+
+    async function launch(step) {
+      let res;
+      try {
+        res = await runStepNode(step, {
+          resultsById,
+          cwd,
+          llmOptions,
+          onStepStart,
+          onStepComplete,
+        });
+      } catch (err) {
+        const o = {
+          id: step.id,
+          status: "failed",
+          taskId: null,
+          result: { summary: `Step threw: ${err.message}` },
+        };
+        resultsById.set(step.id, o);
+        res = { outcomes: [o], failed: true };
+      }
+      stepOutcomes.push(...res.outcomes);
+      active--;
+      if (res.failed) {
+        anyFailure = true;
+        if (!continueOnError) halted = true;
+      }
+      for (const depId of dependents.get(step.id) || []) {
+        remainingDeps.get(depId).delete(step.id);
+      }
+      pump();
+    }
+
+    pump();
+  });
+
+  return { stepOutcomes, anyFailure };
+}
+
 // ─── Execution ───────────────────────────────────────────────────────────────
 
 /**
  * Execute a workflow. The runner for individual tasks must be injected via
  * `_deps.runTask` (signature matches `runCoworkTask`).
  *
+ * Per-step robustness fields (all optional): `retries` (extra attempts after
+ * the first; non-negative integer), `timeoutMs` (per-attempt timeout, positive
+ * number), `retryDelayMs` (base delay before each retry, non-negative number),
+ * `retryBackoff` (`"fixed"` (default) or `"exponential"`).
+ *
+ * Loop nodes (optional, mutually exclusive with `forEach`): `loopWhile` /
+ * `loopUntil` (a `workflow-expr` condition that may reference `${self.<field>}`
+ * — the step's own latest iteration result — and `${iter}`) repeat the step's
+ * task (post-test) until the condition stops it, an iteration fails, or
+ * `maxIterations` (≤ MAX_LOOP_ITERATIONS) is hit. Each iteration inherits the
+ * step's retry/timeout config.
+ *
  * @param {object} options
  * @param {object} options.workflow - Workflow definition
  * @param {string} [options.cwd] - Working directory for history
- * @param {number} [options.maxParallel] - Max parallel steps per batch
+ * @param {number} [options.maxParallel] - Max parallel steps (per batch, or
+ *   concurrent step nodes in pipeline mode)
  * @param {boolean} [options.continueOnError] - Keep running after a failure
+ * @param {boolean} [options.pipeline] - No-barrier scheduling: start each step
+ *   as soon as its own deps finish instead of waiting for the dependency level.
+ *   Defaults to `workflow.pipeline ?? false`. Same outcomes, less idle wait.
  * @param {object} [options.llmOptions] - Forwarded to each task
  * @param {function} [options.onStepStart]
  * @param {function} [options.onStepComplete]
@@ -360,6 +872,7 @@ export async function executeWorkflow(options = {}) {
     llmOptions = {},
     onStepStart,
     onStepComplete,
+    pipeline,
   } = options;
 
   const { valid, errors } = validateWorkflow(workflow);
@@ -370,67 +883,54 @@ export async function executeWorkflow(options = {}) {
     );
   }
 
-  const batches = planBatches(workflow.steps);
+  const usePipeline = pipeline ?? workflow.pipeline ?? false;
   const resultsById = new Map();
-  const stepOutcomes = [];
   const startedAt = new Date(_deps.now()).toISOString();
-  let anyFailure = false;
+  let stepOutcomes;
+  let anyFailure;
 
-  for (const batch of batches) {
-    // Respect maxParallel by slicing batch into chunks
-    const chunks = [];
-    for (let i = 0; i < batch.length; i += maxParallel) {
-      chunks.push(batch.slice(i, i + maxParallel));
-    }
+  if (usePipeline) {
+    ({ stepOutcomes, anyFailure } = await runPipeline({
+      steps: workflow.steps,
+      resultsById,
+      maxParallel,
+      continueOnError,
+      cwd,
+      llmOptions,
+      onStepStart,
+      onStepComplete,
+    }));
+  } else {
+    stepOutcomes = [];
+    anyFailure = false;
+    const batches = planBatches(workflow.steps);
+    for (const batch of batches) {
+      // Respect maxParallel by slicing batch into chunks
+      const chunks = [];
+      for (let i = 0; i < batch.length; i += maxParallel) {
+        chunks.push(batch.slice(i, i + maxParallel));
+      }
 
-    for (const chunk of chunks) {
-      // Expand forEach / when into concrete tasks for this chunk
-      const runnable = []; // { step, message, recordId, parentId }
-      const preOutcomes = []; // outcomes produced synchronously (skipped)
-      for (const step of chunk) {
-        if (anyFailure && !continueOnError) {
-          const outcome = {
-            id: step.id,
-            status: "skipped",
-            taskId: null,
-            result: { summary: "skipped due to earlier failure" },
-          };
-          resultsById.set(step.id, outcome);
-          preOutcomes.push(outcome);
-          continue;
-        }
-        // when-gate
-        let runThis = true;
-        try {
-          runThis = shouldRunStep(step, resultsById);
-        } catch (err) {
-          anyFailure = true;
-          const outcome = {
-            id: step.id,
-            status: "failed",
-            taskId: null,
-            result: { summary: err.message },
-          };
-          resultsById.set(step.id, outcome);
-          preOutcomes.push(outcome);
-          continue;
-        }
-        if (!runThis) {
-          const outcome = {
-            id: step.id,
-            status: "skipped",
-            taskId: null,
-            result: { summary: "when-condition false" },
-          };
-          resultsById.set(step.id, outcome);
-          preOutcomes.push(outcome);
-          continue;
-        }
-        // forEach-expansion
-        if (step.forEach !== undefined) {
-          let items;
+      for (const chunk of chunks) {
+        // Expand forEach / when into concrete tasks for this chunk
+        const runnable = []; // { step, message, recordId, parentId }
+        const preOutcomes = []; // outcomes produced synchronously (skipped)
+        for (const step of chunk) {
+          if (anyFailure && !continueOnError) {
+            const outcome = {
+              id: step.id,
+              status: "skipped",
+              taskId: null,
+              result: { summary: "skipped due to earlier failure" },
+            };
+            resultsById.set(step.id, outcome);
+            preOutcomes.push(outcome);
+            continue;
+          }
+          // when-gate
+          let runThis = true;
           try {
-            items = resolveForEachItems(step.forEach, resultsById);
+            runThis = shouldRunStep(step, resultsById);
           } catch (err) {
             anyFailure = true;
             const outcome = {
@@ -443,97 +943,132 @@ export async function executeWorkflow(options = {}) {
             preOutcomes.push(outcome);
             continue;
           }
-          if (items.length === 0) {
+          if (!runThis) {
             const outcome = {
               id: step.id,
               status: "skipped",
               taskId: null,
-              result: { summary: "forEach items empty" },
+              result: { summary: "when-condition false" },
             };
             resultsById.set(step.id, outcome);
             preOutcomes.push(outcome);
             continue;
           }
-          for (let k = 0; k < items.length; k++) {
-            const childId = `${step.id}[${k}]`;
-            const withItem = substituteItem(step.message, items[k]);
-            const msg = substitutePlaceholders(withItem, resultsById);
+          // loop node — runs its body repeatedly; per-iteration substitution
+          // happens inside runLoopStep, so push the raw template.
+          if (isLoopStep(step)) {
             runnable.push({
               step,
-              message: msg,
-              recordId: childId,
-              parentId: step.id,
+              message: step.message,
+              recordId: step.id,
+              parentId: null,
+              isLoop: true,
             });
+            continue;
           }
-          continue;
+          // forEach-expansion
+          if (step.forEach !== undefined) {
+            let items;
+            try {
+              items = resolveForEachItems(step.forEach, resultsById);
+            } catch (err) {
+              anyFailure = true;
+              const outcome = {
+                id: step.id,
+                status: "failed",
+                taskId: null,
+                result: { summary: err.message },
+              };
+              resultsById.set(step.id, outcome);
+              preOutcomes.push(outcome);
+              continue;
+            }
+            if (items.length === 0) {
+              const outcome = {
+                id: step.id,
+                status: "skipped",
+                taskId: null,
+                result: { summary: "forEach items empty" },
+              };
+              resultsById.set(step.id, outcome);
+              preOutcomes.push(outcome);
+              continue;
+            }
+            for (let k = 0; k < items.length; k++) {
+              const childId = `${step.id}[${k}]`;
+              const withItem = substituteItem(step.message, items[k]);
+              const msg = substitutePlaceholders(withItem, resultsById);
+              runnable.push({
+                step,
+                message: msg,
+                recordId: childId,
+                parentId: step.id,
+              });
+            }
+            continue;
+          }
+          const message = substitutePlaceholders(step.message, resultsById);
+          runnable.push({ step, message, recordId: step.id, parentId: null });
         }
-        const message = substitutePlaceholders(step.message, resultsById);
-        runnable.push({ step, message, recordId: step.id, parentId: null });
-      }
 
-      const promises = runnable.map(async ({ step, message, recordId }) => {
-        if (onStepStart) onStepStart({ stepId: recordId, message });
-        try {
-          const entry = await _deps.runTask({
-            templateId: step.templateId || null,
-            userMessage: message,
-            files: step.files || [],
-            cwd,
-            llmOptions,
-          });
-          const outcome = {
-            id: recordId,
-            status: entry.status,
-            taskId: entry.taskId,
-            result: entry.result,
-          };
-          resultsById.set(recordId, outcome);
-          if (entry.status !== "completed") anyFailure = true;
-          if (onStepComplete) onStepComplete(outcome);
-          return outcome;
-        } catch (err) {
-          anyFailure = true;
-          const outcome = {
-            id: recordId,
-            status: "failed",
+        const promises = runnable.map(
+          async ({ step, message, recordId, isLoop }) => {
+            if (onStepStart) onStepStart({ stepId: recordId, message });
+            let outcome;
+            if (isLoop) {
+              outcome = await runLoopStep({
+                step,
+                recordId,
+                cwd,
+                llmOptions,
+                resultsById,
+              });
+            } else {
+              const r = await runStepWithRetry({
+                step,
+                message,
+                cwd,
+                llmOptions,
+              });
+              outcome = outcomeFromRetry(recordId, r);
+            }
+            if (outcome.status !== "completed") anyFailure = true;
+            resultsById.set(recordId, outcome);
+            if (onStepComplete) onStepComplete(outcome);
+            return outcome;
+          },
+        );
+
+        const results = await Promise.all(promises);
+        stepOutcomes.push(...preOutcomes, ...results);
+
+        // Aggregate forEach children into a parent entry so downstream
+        // `${step.<parent>.summary}` references still work.
+        const byParent = new Map();
+        for (let k = 0; k < runnable.length; k++) {
+          const r = runnable[k];
+          if (!r.parentId) continue;
+          if (!byParent.has(r.parentId)) byParent.set(r.parentId, []);
+          byParent.get(r.parentId).push(results[k]);
+        }
+        for (const [parentId, children] of byParent) {
+          const allOk = children.every((c) => c.status === "completed");
+          const anyOk = children.some((c) => c.status === "completed");
+          const status = allOk ? "completed" : anyOk ? "partial" : "failed";
+          resultsById.set(parentId, {
+            id: parentId,
+            status,
             taskId: null,
-            result: { summary: `Step threw: ${err.message}` },
-          };
-          resultsById.set(recordId, outcome);
-          if (onStepComplete) onStepComplete(outcome);
-          return outcome;
+            result: {
+              summary: children.map((c) => c.result?.summary ?? "").join("\n"),
+              children: children.length,
+            },
+          });
         }
-      });
-
-      const results = await Promise.all(promises);
-      stepOutcomes.push(...preOutcomes, ...results);
-
-      // Aggregate forEach children into a parent entry so downstream
-      // `${step.<parent>.summary}` references still work.
-      const byParent = new Map();
-      for (let k = 0; k < runnable.length; k++) {
-        const r = runnable[k];
-        if (!r.parentId) continue;
-        if (!byParent.has(r.parentId)) byParent.set(r.parentId, []);
-        byParent.get(r.parentId).push(results[k]);
-      }
-      for (const [parentId, children] of byParent) {
-        const allOk = children.every((c) => c.status === "completed");
-        const anyOk = children.some((c) => c.status === "completed");
-        const status = allOk ? "completed" : anyOk ? "partial" : "failed";
-        resultsById.set(parentId, {
-          id: parentId,
-          status,
-          taskId: null,
-          result: {
-            summary: children.map((c) => c.result?.summary ?? "").join("\n"),
-            children: children.length,
-          },
-        });
       }
-    }
 
-    if (anyFailure && !continueOnError) break;
+      if (anyFailure && !continueOnError) break;
+    }
   }
 
   const finishedAt = new Date(_deps.now()).toISOString();