No safeguard when agents spawn many concurrent CPU-heavy shells

Feature Description

While investigating a GitHub issue, the in-app agent spawned 20+ concurrent pytest processes as direct children of the Command Code app. Load average climbed past 220 and the whole machine became unusable, Dock unresponsive, windows slow to respond, other apps starved, and there was no cap, warning, or visibility into any of this from the app side.

The test runs themselves were legitimate work the agent was asked to do. the runs eventually completed and produced useful results. The gap this issue is about: the harness gives no feedback that the system is saturated, and nothing bounds how many heavy jobs can run at once.

Add some form of guardrail or visibility around concurrent background shells. Several approaches are possible, and we would like maintainer input on which direction fits the project:

1. Hard cap, limit the number of concurrent background shells. extra launches queue or are rejected.
2. Warning, surface a warning (toast/log/session note) when a spawned shell would push the system into heavy load.
3. System load UI, add a UI element that tracks system load (load average / CPU pressure) so both the agent and the user can see when the machine is saturated.
4. Customizable cap, user-configurable concurrency limit with a sensible default.
5. Hard cap with option to remove, safe default, opt-out for users who know what they're doing.
6. Spec-aware cap, detect CPU core count / machine specs at initial install and set the default cap accordingly (e.g. min(cores/2, N)).

These are not mutually exclusive:

• 6 could set the default for 4 (customizable cap).
• 3 would be useful regardless of which cap is chosen, load feedback also helps the agent decide to serialize its work instead of fanning out.
• 2 could be a first step toward 1/4/5 once we know what threshold is right.

Curious which trade-off the maintainers prefer. If it helps, a minimal viable version could be: spec-aware default cap (6) + a load indicator (3), both overridable.

Use Case

• The app spawned shells directly (children of the main app process, e.g. ppid = app main PID → /bin/sh -c ... run_tests → 20+ pytest workers).
• Load average trajectory: ~68 (baseline) → 150 → 220+ within the first sweep. a second sweep re-spiked it after the first finished.
• Peak: ~86 runnable processes, load averages 220 / 154 / 88 (1/5/15 min) sustained for minutes.
• User-visible effects while saturated:
  • Dock clicks registered but timed out. app windows appeared frozen.
  • Un-minimizing/restoring a window via accessibility API worked only because the UI events themselves were delayed, not dead.
  • killall Dock was needed to restore Dock responsiveness (worked, but that's a blunt instrument a normal user shouldn't need).
• Memory was not the constraint (86% free, swap 1.3 GB), this was pure CPU/IO saturation, so memory-pressure feedback wouldn't have caught it.
• After the runs ended, Spotlight (mds_stores) re-indexed the file churn at ~98% CPU for an extended period, compounding the tail of the incident.

Additional Context

Environment: Command Code 0.1.37 (CFBundleShortVersionString), Electron desktop app, on macOS 27.0 build 26A428 (macOS Tahoe generation), 10-core Apple Silicon with 64 GB RAM, i.e. a well-spec'd machine still became unusable.

Also observed during the same period: the app's renderer was independently pegged at ~50% CPU due to a stuck drag overlay (separate issue), so WindowServer was under extra redraw pressure. Even so, the load figures (220+) are dominated by the shell fan-out, not the renderer.

Reproduction is inherently workload-dependent. any agent task that fans out many CPU-bound subprocesses triggers the same shape of problem.

Open questions for maintainers:

• Worth deciding which layer owns the limit: shell tool implementation, a supervisor process, or agent-level guidance (e.g. instructions telling the agent to bound its own parallelism).
• If a cap is added, decide the failure mode explicitly: block the spawn, queue it, or spawn but throttle, each has different implications for long agent tasks.
• An opt-out should probably also cover "cap at N but still warn".

Suggested priority for the form dropdown: Important for my workflow.

Automated posting by agentic team with human oversight.