Workflow harness: memory-aware throttling when fanning out subagents

Bug Description
---

Workflow harness: memory-aware throttling when fanning out subagents

Summary

A large Workflow fan-out (deep-research, ~84–92 subagents) drove the host out of
memory and crashed the terminal mid-run. The concurrency cap is count-based
(min(16, cores-2)), not memory-aware, so N heavy agents each holding large
fetched-page / file contexts can exhaust RAM even though the count is within
limits.

Environment

• Claude Code Workflow tool (deep-research bundled workflow)
• Host: 16 GiB RAM, competing with Chromium-based apps (Vivaldi browser, VSCode/Electron)
• Observed: OOM at roughly 84–92 concurrent/total research agents; full run journaled

84 started / 77 completed before the crash.

What happened

1. deep-research fanned out: scope → 5 search → ~15 fetch → 3-vote verify (many) → synthesize.
2. Peak concurrent agents (up to ~16), each carrying fetched web-page context, spiked RAM.
3. Host hit OOM; terminal process was killed.
4. Resume (resumeFromRunId) recovered cleanly — 77 cached agents replayed instantly,

only the interrupted tail + synthesis re-ran, at a fraction of the memory footprint.

Impact

• Hard crash (lost the live console) rather than graceful degradation.
• Recovery exists (resume-from-cache) but is reactive; nothing prevents the OOM.

Suggested improvement

Make the fan-out memory-aware in addition to count-aware:

• Sample available RAM (e.g. /proc/meminfo MemAvailable) and shrink the active

concurrency window when headroom drops below a threshold.

• Optionally surface a pre-flight estimate before a big fan-out:

"spawning N agents, est. peak ~X GB; M GB available" — and auto-throttle or warn.

• Treat the existing resume-from-cache as the recovery half; add this as the

prevention half.

Repro sketch

• On a RAM-constrained host (≤16 GB) with browsers/Electron open, launch a

deep-research workflow whose verify phase produces dozens of agents.

• Watch peak concurrent agents exhaust RAM → OOM.

Notes

• The resume design is excellent and did its job; this is purely about avoiding

the crash in the first place.

---

Environment Info

• Platform: linux
• Terminal: xterm-256color
• Version: 2.1.177
• Feedback ID: bc7ff916-2976-4f1a-9004-f0c647cfa3db