Improvement: lower default `maxConcurrent` and raise `shellInitDelayMs`

[jayminwest]

Source

Decomposed from #84 (Chapter 4).

Summary

Two default config values are aggressive for new users:

• maxConcurrent: 25 — Too many for a first experience. New users exploring overstory will accidentally spawn too many agents before understanding the cost model. Suggest defaulting to 5 with a comment suggesting 25 for experienced users.

• shellInitDelayMs: 0 — Will bite anyone with a non-trivial shell (starship, nvm, pyenv, mise, etc.). Suggest defaulting to 1000ms, or auto-detecting slow shells during ov init.

Related

• Narrative: User Experience Report #84 (parent narrative)

[lucabarak]

For context — shellInitDelayMs was added in PR #60 (merged Feb 28) specifically for this use case. It's configurable per-project in .overstory.yaml:

runtime:
  shellInitDelayMs: 200  # milliseconds to wait after shell init before polling TUI readiness

Default is 0 (no delay). The config validator warns on negative values and on delays >30s. It hooks into both coordinator.ts and sling.ts spawn paths.

This issue's suggestion to lower maxConcurrent is a separate lever — reducing parallel spawns decreases system load during init, which indirectly reduces the window where shell init races can occur. The two settings complement each other: shellInitDelayMs adds per-agent breathing room, maxConcurrent reduces overall spawn pressure.

Worth considering whether a reasonable non-zero default for shellInitDelayMs (e.g., 50-100ms) would help out-of-the-box on slower machines without requiring config changes.

[RogerNavelsaker]

Opened a PR that partially addresses this from the orchestration side: #127

This does not change the default maxConcurrent or shellInitDelayMs values yet.
What it does change is the role behavior when users intentionally keep agent counts low:

• coordinators can fall back to direct scout/builder dispatch for narrow work streams
• leads can compress into combined lead/worker mode when --dispatch-max-agents is 1 or 2

That should reduce the feeling that small-budget runs still require the full coordinator -> lead -> scout/builder/reviewer chain to make progress.