Wave Execution: The Fix That Saved One-Shot Scripts

🚨 The Symptom

One-Shot Scripts v1.7 introduced Max Agent Teams — 3 to 5 agents launching simultaneously per phase. It was a massive speed upgrade on paper.

Then users started reporting that their terminal was freezing. The Claude Code window would drop to roughly 1 frame every 5 minutes. Completely unusable. But here's the weird part: the rest of the computer was fine.

🕵️ The Investigation

First stop: Task Manager. We needed to see exactly what processes were running and how much they were consuming.

The process snapshot told a clear story of resource overload:

PROCESS SNAPSHOT (during freeze)
================================
claude.exe     1.2 GB RAM    (instance 1)
claude.exe     1.2 GB RAM    (instance 2)
bash.exe       x 11 instances (spawned by agents)

CPU TIME ANALYSIS:
  Kernel mode:  FLAT (no change over 30s)
  User mode:    TICKING (incrementing slowly)
  I/O reads:    ZERO
  I/O writes:   ZERO

Two full Claude instances eating 1.2 GB each. Eleven bash shells spawned by the concurrent agents. That's a lot of processes fighting for the terminal renderer's attention.

🧟 The Zombie That Wasn't Dead

Looking at the CPU time data, the initial call was obvious: this session is dead. Kernel mode was flat, meaning no system calls. No I/O activity at all. Classic zombie process — time to kill it and start over.

But then we spotted something. The user mode time was still ticking. Not fast, but it was incrementing. The session wasn't dead — it was alive, just glacially slow.

The pattern was specific: user mode ticking but kernel mode flat. That meant the Electron process was spending all its time on UI overhead (trying to render agent status streams) but making zero API calls. The backend was alive — the frontend was choking.

🎯 Root Cause

Claude Code's terminal renderer wasn't built to handle 3–5 concurrent agent status streams updating simultaneously. Each agent produces its own stream of output — tool calls, file reads, code writes, status updates.

Multiply that by 5 agents and the renderer falls over. It's not a memory issue or a CPU issue — it's a rendering throughput issue. The UI simply can't paint that many concurrent status updates fast enough.

🌊 The Fix: Wave Execution

The solution was simple in concept: keep the same total agents per phase, but don't launch them all at once. Instead, launch them in waves of maximum 2 concurrent agents.

A phase that needs 5 agents still gets 5 agents. They just run in waves instead of a stampede:

The instruction added to every phase script was explicit:

WAVE LIMIT: Max 2 agents concurrent per wave.
Do NOT reduce total agent count.

Example for 5 agents:
  Wave 1: Agent A + Agent B (run simultaneously)
  Wave 2: Agent C + Agent D (run simultaneously)
  Wave 3: Agent E (runs alone)

Total agents: still 5. Concurrency: max 2.

🤯 The Misinterpretation

Here's where it gets interesting. The first version of the fix said "wave limit: max 2 concurrent." Seemed clear enough. But the model read it as "max 2 agents total per phase."

Instead of launching 5 agents in waves of 2, it was only launching 2 agents total. That's a massive quality regression — you've cut your research and testing capacity by more than half.

📊 Before and After

🚗 The Real-World Analogy

Think of a highway on-ramp during rush hour. Without metering, 50 cars try to merge onto the highway at the same time. The highway grinds to a halt — nobody moves, everyone's stuck.

Install a ramp meter that lets 2 cars through every few seconds and something magical happens: the same number of cars get through, they just don't all try to merge at once. Traffic flows. No gridlock. Same throughput, dramatically better flow.

Wave execution is ramp metering for AI agents. The throughput is identical — you're just preventing the bottleneck that kills everything.