study-adaptive-parallelism

Metadata

Description

## Objective
Study and design the control loop that adjusts project parallelism (max_agents) from the rate-limit signal so WG slowly balances credits vs work-rate — riding at ~100% of allocated resources without tripping limits — with budgeting expressed in cost/time.

## Research questions
- Control objective: define "100% of allocated resources" operationally (target utilization, max spend/min, near-zero 429s). Additive-up / subtractive-down policy and hysteresis to avoid oscillation.
- Inputs: the failure-reason signal from the telemetry study + measured throughput/cost. How fast to react to a sustained rate-limit vs a blip.
- The max_agents authority problem found this session: the running daemon carries a `--max-agents` launch arg that a `service reload` silently overrides with the profile value (observed 2 -> 8 on reload). Design how the controller authoritatively sets effective max_agents and survives reload/restart (config vs launch arg vs profile vs runtime RPC).
- Budgeting: express limits as cost/time (e.g. USD/hr, N requests/min) per provider/model; how to translate a budget into a max_agents cap; per-project vs global.
- Safety: hard floor/ceiling, cooldown after a cut, human override, and a kill-switch. Metrics that prove it is working (utilization, spend rate, 429 rate).
- Interaction with the supervisor hard-agent (who does what — the controller owns the parallelism knob; the supervisor owns reset).

## Inputs
- The max_agents launch-arg-vs-profile-vs-reload behavior observed this session
- src/ coordinator/dispatch (max_agents plumbing), config profile files (~/.wg/profiles/*.toml, .wg/config.toml)
- OpenRouter cost/rate data from the telemetry study

## Deliverable
docs/studies/adaptive-parallelism-budget-design.md

## Validation
- [ ] Design doc committed at docs/studies/adaptive-parallelism-budget-design.md
- [ ] Defines the control objective, up/down policy, hysteresis, and cost/time budget model
- [ ] Solves the max_agents authority / reload-override problem concretely (cites the code path)
- [ ] Specifies floors/ceilings/cooldown/kill-switch and the metrics that prove it works
- [ ] Defines the boundary with the supervisor hard-agent

Depends on

• (none)

Required by

• done .flip-study-adaptive-parallelism
• done synthesis-roadmap-from

Log

• 2026-07-25T13:24:02.927085515+00:00 Task paused
• 2026-07-25T13:24:23.701219099+00:00 Task published
• 2026-07-25T14:08:29.982057362+00:00 Spawned by coordinator --executor pi --model zai:glm-5.2 --isolation required-worktree
• 2026-07-25T14:09:02.172515785+00:00 Starting research: exploring max_agents plumbing, config/profile authority, and rate-limit signal sources
• 2026-07-25T14:17:49.465196543+00:00 Committed: 66bba428 — pushed to remote. Design doc at docs/studies/adaptive-parallelism-budget-design.md (633 lines).
• 2026-07-25T14:17:49.795228964+00:00 Validated: all 5 checklist items met — control objective/up-down/hysteresis/budget model (§2,4,5,6), authority fix cites ipc.rs:1111 + mod.rs:2415 + profile_cmd.rs:1205 (§8), safety floor/ceiling/cooldown/kill-switch + metrics (§7,10), supervisor boundary (§9). All line citations verified exact.
• 2026-07-25T14:18:03.095624088+00:00 Task marked as done; scheduled evaluator is advisory evidence only (execution is not a quality pass)