threnody-swarm

Threnody swarm orchestration

Default: host-native swarms

For MCP host callers (Claude, Copilot, Cursor, Codex, etc.), execute_swarm defaults to host_native:

1. Threnody plans the task.
2. Returns awaiting_host_execution: true + host_spawn_waves.
3. You spawn host Task/Agent per wave — Threnody does not subprocess.

This path is unaffected by utility-only delegation rules.

Fast-start contract

Agent-emitting swarm paths must return host_spawn_waves quickly: target under 5 seconds to a spawnable handoff and under 30 seconds to first host spawn. Use the fast host-native handoff first; optional refinement, consensus, learning aggregation, and detailed receipts happen after the first worker wave starts or at terminal reporting.

Within each wave, spawn every agent as the same batch before waiting on the wave barrier. A host loop that starts one same-wave agent, waits, then starts the next is a fast-start regression.

Token discipline applies to all swarm shapes: keep host-native handoff compact, prefer bounded file-level fanout for broad sweeps, and reserve star/consensus or high-tier synthesis for explicit deep-risk work.

Workflow

1. If not already planned, follow threnody-plan (plan-only swarm preview stops before spawn).
2. Optionally route_task for tier context.
3. execute_swarm(task, topology?, max_agents?, budget_limit?, workspace_root) — always pass workspace_root. Target paths are containment-checked against it; omit it and the server falls back to its own cwd and answers with workspace_root_source: "cwd_fallback" plus a workspace_root_warning.
4. Handle response:
   • awaiting_host_execution + host_spawn_waves — execute waves via host agents. The response carries plan_summary, not a full plan object (all runs, not just review runs). Spawn from host_spawn_waves; read plan_summary.coverage for file accounting — a non-empty coverage.deferred means a named file has no owner, and coverage.packed means the agent budget merged files into fewer agents. Full plan fidelity stays server-side (inspect_run_receipt).
   • preview: true + preview_token — cost over budget; confirm then re-call with token.
   • started: true (delegate mode only) — Threnody subprocess orchestrator running.
   • Check learning_report_contract.report_mode (batch default, or inline).
5. Reporting — depends on report_mode:
   • batch (default): Do NOT call report_host_wave for plain worker waves. Just spawn each wave natively. Per-agent learning is captured automatically (PostToolUse hook) or, when learning_capture=model, by passing the agents to the single terminal call. This is the fast path — no per-wave MCP round-trip.
   • inline (legacy): call report_host_wave after each wave with workspace_root and per-agent results (task_id, spawn_id, success, touched_files, output_excerpt).
6. Mid-run expansion (both modes): after scaffold/contract waves, call expand_host_plan(discovered_files=[...]) to spawn additional file-scoped agents.
7. Terminal: call report_host_swarm_complete(outcome=accepted|revised|reworked|rejected) once at the end (in batch mode this imports the whole run and finalizes). In inline mode you may instead set terminal=true on the last report_host_wave. Verify finalize.swarm_outcome.stored.
8. Monitor:
   • Host-native: inspect_swarm for status; optional inspect_status.
   • Delegate: list_subtasks, resume_swarm_inspect, resume_swarm_confirm.