Problem and outcome

executeLoopNode and executeLoopGroupBody were single functions of about 1,500 and 1,000 lines (cognitive complexity 539 and 259). Their resume prelude and per-iteration body could not be read, tested or changed without holding the whole function in your head. This is steps R2 and R3 of lane R in #1140.

• Outcome: both executors read as resume detection, setup, and one call per iteration. Every extracted function scores 15 or lower on the A complexity ratchet whose baseline the change cannot edit #3020 scorer. executeLoopNode goes 539 to 39, executeLoopGroupBody 259 to 9.
• Invariant: no behavior change. Every value, event, log key and message is the same, and the public entries stay where they are.
• Scope boundary: helpers stay inside dag/nodes/loop/ and dag/nodes/loop-group/. No new field on RunLayersContext, no new dependency, no test changes.

Known failing check, not from this change: bun run test src/dag/ has one failure, executeDagWorkflow -- durable wait node > persists a future wait and returns without invoking a provider. It fails the same way at the starting commit, and src/dag/nodes/wait/ alone passes 18/18. The wait node is untouched.

Review guidance

• Feedback requested: value identity. Closure variables became fields on shared state objects, so check that each one is read and written at the same moment as before.
• Start here: packages/workflows/src/dag/nodes/loop/loop-state.ts — LoopRun (fixed for the node) and LoopState (what iterations used to share through closures) define the seam for R2. For R3 it is loop-group/loop-group-state.ts.
• Review order: commit 1 (loop), then commit 2 (loop_group). In each, the state file, then loop.ts / loop-group.ts, then iteration*.ts and resume.ts. Diff with --color-moved=dimmed-zebra --color-moved-ws=allow-indentation-change to dim the moved lines.
• Lower-attention areas: the bodies of the iteration*.ts functions are the original code moved, with ctx. / state. prefixes.
• Known risk or uncertainty: the loop's attempt loops now take the iteration's resume session as a value computed once at the iteration start. The original read the same value before the first attempt and never re-derived it, so attempts after a transient retry still resume the pre-iteration session, not one a failed attempt reported.

Solution

R2, loop. loop.ts keeps executeLoopNode, readLoopResume and finalizeOnBareApprove. The iteration moves into iteration.ts (stop check, events, completion channels, until_bash, completion record, interactive gate), iteration-stream.ts (retry and reask attempt loops, result chunks, usage folding) and iteration-outcome.ts (judging an attempt: cancelled, empty, unsettled, transient retry, structured-output gate).

R3, loop_group. resume.ts holds resume-shape detection, owner session cursor restore, the bare-approve finalize, the terminal wait resume, the $LOOP_PREV snapshot restore and the escalated completion check. iteration.ts holds the per-iteration body. The two until_bash sites share one subprocess and rejection path in until-bash.ts, each keeping its own order of path resolution, artifact listing and substitution.

Finalize-on-approve is not unified. The plan said to unify only if byte-identical. They are not: the loop records a completed execution through finalizeLoopFromSignal with the gate's usage and session, while the group returns its output and lets executeLoopGroupNode record it. dag/loop-completion.ts is untouched. A group comment that pointed at a finalizeLoopFromSignal call the group never makes was corrected.

Dropped as dead: the per-iteration AbortController, provider event handler and cancel-check clock that the original created and then overwrote at the start of every attempt.

Validation

• bun run type-check in packages/workflows and bun run lint at the root (cleanup-drift, persistence and SDK drift checks included) — pass.
• bun run scripts/check-ratchet.ts against origin/dev after each commit — pass, no Ratchet-Allow trailer needed.
• bun run test src/dag/nodes/loop/ src/dag/nodes/loop-group/ — 189 pass, 0 fail. The same command at the starting commit gives 189 pass, so the moved suites keep their count. No tests were deleted.
• dag-executor, executor, run-resume, fixture-runner, packaged-workflow and dry-run test files, each run alone — all pass (12, 185, 12, 57, 3, 115).
• bun run test src/dag/ — 1066 pass, 1 fail: executeDagWorkflow -- durable wait node > persists a future wait and returns without invoking a provider. It fails the same way at the starting commit, and src/dag/nodes/wait/ alone passes 18/18. The wait node is untouched.
• Not verified: passing several top-level test files to one bun run test call gives mass mock-pollution failures. That combination is not a valid check, so each file was run separately.

Links

• Closes 1140 R2–R3: R2 loop; R3 loop_group #4566
• Part of architecture: simplify workflow engine boundary across executor.ts and dag-executor.ts #1140

Summary by CodeRabbit

• New Features
  • Added support for resuming paused loops and loop groups, restoring prior outputs and session context.
  • Loops and loop groups can now finish based on configured completion signals, including Bash checks, or pause for interactive approval.
  • Added structured-output validation and re-asks, transient retries, and clearer handling of cancelled or failed iterations.
  • Iteration results and usage are tracked across runs and included when reporting completion or failure.