feat(sprout-acp): parallel agent pool, heartbeat timer, and just goose recipes

[tlongwell-block]

Summary

Run up to N agent subprocesses in parallel with optional periodic heartbeat prompts. Adds just goose convenience recipes for launching agent harnesses.

N=1 preserves fully backward-compatible behavior — no config changes needed for existing deployments.

What Changed

File	Change	Δ
pool.rs	New — AgentPool, OwnedAgent, take-and-return ownership, run_prompt_task	+551
main.rs	Rewritten — 5-branch biased select!, dispatch/recovery helpers, shutdown sequence	+456 −284
queue.rs	Multi-channel in-flight (HashSet), retry throttle, requeue_preserve_timestamps	+371 −49
config.rs	--agents, --heartbeat-interval, --heartbeat-prompt, --heartbeat-prompt-file	+127 −1
README.md	Parallel agents docs, config examples, shared identity note, heartbeat semantics	+57 −4
justfile	just goose (foreground) + just goose-bg (screen session) recipes	+45
acp.rs	#[allow(dead_code)] on pre-existing unused Timeout variant (clippy fix)	+1

Architecture

                  ┌──────────────────────────────────────────────────┐
                  │              sprout-acp harness                  │
                  │                                                  │
Relay ──WS──────▶│  EventQueue ──▶ AgentPool ─┬─ Agent[0] → goose  │
                  │       ▲           ▲  │     ├─ Agent[1] → goose  │
heartbeat tick ─▶│       │           │  │     └─ Agent[2] → goose  │
                  │       │    result_rx ◀┘                          │
                  │       └───────────┘                              │
                  │     redispatch on every result                   │
                  └──────────────────────────────────────────────────┘

5-branch biased; select loop:

1. Results (highest priority) — drain completions before accepting new work
2. Panics — JoinSet + task_map with JoinError::id() → O(1) agent identification and recovery
3. Relay events → queue → dispatch to available agents
4. Heartbeat (lower priority) — skipped when all agents busy
5. Shutdown — unified SIGINT + SIGTERM via watch::channel, grace period + JoinSet::shutdown()

Key Design Decisions

• Take-and-return pool — AcpClient is not Clone. Agent moves out of slot on claim, back on return. No Arc<Mutex<>>.
• rx_and_join_set() split-borrow — polls result channel and JoinSet in one select without double-borrowing the pool
• Per-channel in-flight — HashSet<Uuid> ensures the same channel is never processed by two agents simultaneously
• Channel affinity — best-effort: prefer the agent that already has a session for that channel
• Retry throttle — HashMap<Uuid, Instant> with 5s backoff on failed channels, prevents tight retry loops
• !join_set.is_empty() guard — prevents 100% CPU spin when no tasks are in flight (JoinSet returns None immediately when empty)
• Box<PromptResult> in PoolEvent — clippy large_enum_variant: PromptResult (~528B) vs JoinError (~24B), boxed to avoid bloating the enum
• Heartbeat: at-most-one globally — next tick suppressed until current completes; lower priority than queued events

Configuration

# Default (backward compatible)
sprout-acp

# 4 parallel agents
sprout-acp --agents 4

# 2 agents with 5-minute heartbeat
sprout-acp --agents 2 --heartbeat-interval 300

# Via justfile
just goose agents=2 heartbeat=300

Flag	Env Var	Default	Description
--agents	SPROUT_ACP_AGENTS	1	Agent subprocess count (1–32)
--heartbeat-interval	SPROUT_ACP_HEARTBEAT_INTERVAL	0	Seconds between heartbeats (0=off, ≥10)
--heartbeat-prompt	SPROUT_ACP_HEARTBEAT_PROMPT	built-in	Custom heartbeat prompt text
--heartbeat-prompt-file	SPROUT_ACP_HEARTBEAT_PROMPT_FILE	—	Read heartbeat prompt from file

Testing

• 116 unit tests pass (24 queue, 31 config, 61 existing)
• E2E verified against live relay:
  • N=1: backward compatible, 0% CPU idle ✅
  • N=2: concurrent channel processing ✅
  • Heartbeat (30s interval): fires on schedule, 0% CPU between ticks ✅
• Crossfire reviewed: Opus 9/10 APPROVE, Codex 9/10 APPROVE

Follow-Up (deferred from review)

• Unit tests for AgentPool::try_claim / return_agent / live_count
• Carry task_id through PromptResult for explicit invariant checking
• Document shutdown event-drop tradeoff in operator docs
• Respawn backoff on repeated agent crashes