[Epic] Port DevSwarm into forge — swarm orchestration + 37 MCP tools

[justrach]

Goal

Port the orchestration capabilities of justrach/devswarm into forge as a native, trackable layer on top of the existing crates. DevSwarm exposes 37 MCP tools that wrap parallel agent orchestration, task chains, review-fix loops, code-intelligence (blast-radius), and GitHub project management. The goal of this epic is to bring those capabilities into codegraff so we get the same multi-agent leverage without running a second MCP server.

Why this is worth doing

• We already hit single-agent ceilings: see P0: agents stuck in analysis-paralysis loop — re-read same files, never write code #27 (analysis-paralysis loop).
• The Hermes-class harness in graff-agent: Hermes-class harness in a NEW repo, prerequisites in codegraff #34 wants the same orchestrator → workers → synthesizer pattern devswarm already implements.
• Plugin hooks ([P2-8] Plugin lifecycle hooks: pre/post tool, pre/post LLM, session start/end (Rust HookRegistry + SDK plugins.on) #42), ExecutionEnvironment trait ([P2-9] ExecutionEnvironment trait + Local impl + SDK exec.registerEnvironment (route shell tools through trait) #43), and the interactive multi-turn harness (Interactive multi-turn test harness for agents #20) are all prerequisites or adjacent to what swarm execution needs.
• DevSwarm has spent ~440 closed issues converging on the right shapes (allocator discipline, MCP shutdown handling, worker tool-scoping, worker-prompt isolation). We get to skip those mistakes.

DevSwarm capabilities being ported

Tools (37 total, 7 categories)

• Agents (7) — run_agent, run_swarm, run_task, review_fix_loop, run_reviewer, run_explorer, run_zig_infra → [DSP-1] Agents: port run_swarm / run_task / review_fix_loop + role+mode routing from devswarm #55
• Planning (4) — decompose_feature, get_project_state, get_next_task, prioritize_issues → [DSP-2] Planning tools: decompose_feature / get_project_state / get_next_task / prioritize_issues from devswarm #58
• Issues (7) — create_issue, update_issue, close_issue, get_issue, create_issues_batch, close_issues_batch, link_issues → [DSP-3] Issues tools: create/update/close/get + batch + link_issues from devswarm #59
• Git (6) — create_branch, get_current_branch, commit_with_context, push_branch, recently_changed, git_history_for → [DSP-4] Git tools: branch ops, commit_with_context, push_branch, recently_changed, git_history_for from devswarm #56
• Pull Requests (6) — create_pr, get_pr_status, list_open_prs, merge_pr, get_pr_diff, review_pr_impact → [DSP-5] Pull Request tools: create/status/list/merge/diff + review_pr_impact from devswarm #54
• Code Intelligence (6) — blast_radius, relevant_context, symbol_at, find_callers, find_callees, find_dependents → [DSP-6] Code Intelligence: blast_radius, relevant_context, symbol_at, callers/callees/dependents from devswarm #57
• Patterns & Telemetry — orchestrator/synthesizer, role+mode routing, task chain presets, review-fix termination, anonymous telemetry → [DSP-7] Patterns & Telemetry: orchestrator/synthesizer, task chains, review-fix termination, anonymous telemetry from devswarm #60

Core patterns

• Orchestrator/Synthesizer: Orchestrator (Opus-tier) decomposes a swarm task → workers (Sonnet-tier) execute in parallel → synthesizer (Sonnet-tier) aggregates one cohesive output.
• Role + Mode routing: 8 roles (finder/reviewer/fixer/explorer/architect/orchestrator/synthesizer/monitor) × 4 modes (smart/rush/deep/free). Each role pins a default model tier (Sonnet for most, Opus for architect/orchestrator, Haiku for monitor).
• Task chains: preset chains — finder_fixer, reviewer_fixer, explore_report, architect_build.
• Review-fix loop: iterate reviewer→fixer until reviewer returns NO_ISSUES_FOUND or hits max-iter.
• Blast radius: static analysis of what code is affected by a change — risk surface before/after.

Overlap with already-open codegraff issues (do NOT duplicate)

Existing issue	DSP category	Relationship
#34 graff-agent Hermes harness	#55, #60	Same orchestrator/synthesizer goal; do this work inside the Hermes harness scope when applicable.
#27 P0: agents stuck in analysis-paralysis loop	#55, #60	Role+mode routing + review-fix termination is the proposed cure.
#42 [P2-8] Plugin lifecycle hooks	#55	Swarm workers need pre/post tool & pre/post LLM hooks for telemetry + tool-scoping.
#43 [P2-9] ExecutionEnvironment trait	#55	Workers need worktree isolation (see devswarm's ADR-001 / their issue #213).
#20 Interactive multi-turn test harness	#60	Needed to evaluate swarm role prompts; devswarm's open #354 has the same gap.
#28, #33 trajectory observability	#60	Telemetry/observability for swarm runs lands on top of these.

Out of scope for this epic

• Devswarm's own evolutionary self-improvement track (devswarm #148 family). We can revisit after the 7 children are landed.
• Building a competing MCP server. We're porting the capabilities into forge tools / SDK surface, not standing up another stdio binary.

Bug-class lessons from devswarm's closed issues (apply during port)

When implementing children, watch for these patterns devswarm hit and burned days fixing:

• Worker prompt bleed (devswarm #389): swarm workers must not embed the orchestrator preamble into the worker task text.
• Role enforcement (devswarm #388): workers must run the role they were assigned, not default to fixer.
• Tool scoping per role (devswarm #374): workers should not inherit all MCP tools — scope to the role.
• MCP shutdown (devswarm #387): respect client shutdown/exit. (Applies to our MCP exposure too.)
• Repo binding (devswarm #379): a global-mode forge MCP server must bind to the caller's cwd, not its own.
• Config caching (devswarm #376): don't re-read config N+2 times per swarm.
• Env inheritance (devswarm #390): nested subprocess spawns must not inherit parent desktop session vars.

Acceptance criteria for the epic as a whole

• All 7 children ([DSP-5] Pull Request tools: create/status/list/merge/diff + review_pr_impact from devswarm #54–[DSP-7] Patterns & Telemetry: orchestrator/synthesizer, task chains, review-fix termination, anonymous telemetry from devswarm #60) are landed or explicitly deferred.
• Swarm runs surface in the forge TUI / SDK as first-class commands.
• At least one full task-chain preset (reviewer_fixer is the obvious one) runs end-to-end against this repo and closes the loop on a real issue.
• Bug-class lessons above are encoded as tests or comments in the relevant crate(s).