feat(desktop): cap OpenClaw agent parallelism at 5

[wpfleger96]

OpenClaw connects to a single shared Gateway daemon. Spawning the default 10 ACP workers per agent is both resource-expensive and architecturally wrong — each worker opens a separate gateway connection. Tyler's ruling: cap at 5, lower if needed.

Contract

Store the requested value (1–32) verbatim at every persistence and wire boundary. Apply effective = min(requested, harness_cap) only at the four enforcement points:

Boundary	Implementation
Local spawn	BUZZ_ACP_AGENTS env var in child Command
Remote deploy	launch.policy_env["BUZZ_ACP_AGENTS"] + legacy parallelism field
Restart badge	SpawnConfigSnapshot.parallelism stores effective value; the diff surface displays what actually runs
UI copy	Amber hint when requested > cap; no max attribute, no save-path clamp

BUZZ_ACP_AGENTS is added to RESERVED_ENV_KEYS — the Desktop resolves the effective value into policy_env; a user-supplied override in env would bypass the cap and is silently stripped.

Changes

managed_agents/parallelism.rs (new) — policy core:

• OPENCLAW_MAX_PARALLELISM = 5
• harness_max_parallelism(command) — keyed on normalize_command_identity so path prefixes, .exe suffixes, and other cosmetic differences are ignored
• effective_parallelism(command, value) — identity for uncapped harnesses
• acp_agents_value(command, parallelism) — env("BUZZ_ACP_AGENTS", …) helper

runtime.rs — spawn clamp: BUZZ_ACP_AGENTS = acp_agents_value(effective_command, record.parallelism)

agents_deploy.rs — deploy egress clamp: build_deploy_payload resolves effective_parallelism once from descriptor.command; both launch.policy_env["BUZZ_ACP_AGENTS"] and the legacy top-level parallelism field use that value — the two are always consistent regardless of stale record.agent_command pins

spawn_snapshot.rs — from_inputs stores effective_parallelism(&descriptor.command, record.parallelism) in the parallelism field. Over-cap edits that don't change the pool (e.g. 10 → 8, both clamp to 5 on OpenClaw) produce equal snapshots; cap crossings (8 → 3) produce different snapshots.

AcpRuntimeCatalogEntry.max_parallelism: Option<u32> — derived from the static definition command, not the probed entry.command (which may be null for unavailable entries), so unavailable OpenClaw entries still carry the cap. Propagated through all four catalog constructors (builtin discovery, preset catalog construction, custom discovery, custom-save response), IPC types (RawAcpRuntimeCatalogEntry.max_parallelism), and the frontend catalog type.

UI — EditAgentAdvancedFields and PersonaAdvancedFields show an amber hint when selectedRuntime.maxParallelism is set and the current value exceeds it. Cap and label come from the catalog entry — no hardcoded 5 in TS. No max attribute on inputs; the input stays type="text" with 1–32 copy.

Docs — docs/remote-agents.md: BUZZ_ACP_AGENTS moved from the deliberately-non-reserved section to reserved; new contract documented. desktop/src/features/agents/AGENTS.md: command-keyed execution policy documented as the sanctioned second metadata source feeding the catalog projection.

Tests

Rust (parallelism.rs):

• policy_table — harness_max_parallelism and effective_parallelism across all openclaw variants and uncapped harnesses
• acp_agents_value_openclaw_above_cap_is_capped — spawn-env seam
• override_direction_* — both override directions (openclaw runtime + goose override; goose runtime + openclaw override)
• summary_persona_inherited_* — live persona wins over stale agent_command
• snapshot_export_carries_requested_definition_parallelism — requested value travels wire/sync unchanged

Rust (spawn_snapshot/tests.rs):

• openclaw_above_cap_parallelism_snapshots_equal — stored 10 vs 8, both clamp to 5 → snapshots equal
• openclaw_cap_crossing_parallelism_snapshots_differ — 8 (clamps to 5) vs 3 → snapshots differ

Rust (discovery/presets.rs):

• openclaw_preset_unavailable_carries_max_parallelism / openclaw_preset_available_carries_max_parallelism — catalog metadata present with command: null and with a resolved path

Rust (agents_deploy.rs):

• launch_block_openclaw_over_cap_policy_env_is_capped — direct launch.policy_env seam
• deploy_payload_json_stale_goose_record_live_openclaw_descriptor_both_capped — stale record.agent_command=goose, live descriptor=openclaw: both fields cap to 5
• deploy_payload_json_stale_openclaw_record_live_goose_descriptor_both_uncapped — stale record.agent_command=openclaw, live descriptor=goose: both fields pass through requested
• deploy_payload_json_explicit_openclaw_override_both_capped — explicit agent_command_override=openclaw: both fields cap to 5

Rust (persona_events/stale_pin_tests.rs):

• apply_persona_snapshot_goose_to_custom_harness_drops_stale_goose_pin — custom-direction stale-pin drop (builtin pin → loaded custom harness via update_loaded_harness_registry)

TypeScript (agentParallelism.test.mjs):

• parallelismCapHint — at/below cap (null), above cap (hint includes label and cap value), singular form for cap=1, uncapped harness (null)

TypeScript (tauri.test.mjs):

• fromRawAcpRuntimeCatalogEntry round-trips max_parallelism → maxParallelism; absent when undefined

[wesbillman]

Reviewing on Wes Pfleger's behalf.

The executable launch block and the legacy top-level parallelism field can disagree for inherited or overridden harnesses. build_deploy_payload has already resolved the effective harness into descriptor and uses descriptor.command to cap launch.policy_env["BUZZ_ACP_AGENTS"] (lines 131–142), but deploy_payload_json recomputes the legacy value from record.agent_command (lines 185–189). That field is explicitly a stale create-time snapshot in several supported states: record_agent_command instead prefers agent_command_override, then record.runtime, then the live persona (managed_agents/discovery.rs:308–330). For example, an agent whose stored agent_command is goose but whose live persona now resolves to OpenClaw will execute with BUZZ_ACP_AGENTS=5 while the top-level field still says 10; the opposite transition reports 5 while running 10.

Please derive both projections from the same already-resolved descriptor (for example, pass the effective command/value into deploy_payload_json) and add regression coverage for stale persona inheritance and/or an explicit override. Otherwise the new "display/bookkeeping consistency" guarantee is precisely where the dungeon floor opens.

[wesbillman]

Re-reviewing on Wes Pfleger’s behalf.

The requested deploy correction is in place: build_deploy_payload computes effective parallelism once from the resolved descriptor.command, and both the executable launch.policy_env["BUZZ_ACP_AGENTS"] and legacy top-level parallelism now receive that same projection. The added stale-persona and explicit-override regression cases cover the mismatch that blocked the prior head.

I also reviewed the incremental fix and merge result; no new blocking issues found. CI is green at the reviewed head.