#56: a created run only seeds the task; if no expert agent connects, the run hangs
at `running` forever with no `agent.*` events and an empty /result — and the cause
(P-guard already detects NO_AGENTS_CONNECTED) was only in run.metadata["health"] /
/diagnostics, never on the surfaces HM/cockpit actually poll (/events, /result).
This makes a stuck run explain itself (no new Manager event type, no contract change):
- launch_swarm_agents now records run.metadata["agent_launch"]
{backend, planned, launched, launched_ids, model_key_resolved, note}. The note
pinpoints WHY there are 0 agents — e.g. AGENT_LAUNCH_BACKEND=none (no auto-launch),
k8s launch failed (kubectl/RBAC + Pod Workload Identity, #16/#60 A.3), or the model
key didn't resolve. No secret recorded — only a model_key_resolved bool.
- /result and /diagnostics now carry `health` (P-guard blockers) + `agent_launch`.
- assess_swarm_health emits ONE `timeline.updated` per distinct blocker-set (registered
event; dedup by summary, reset when healthy) so /events and the cockpit (#39) show
"swarm blocked: no_agents_connected" instead of silence. Still NO unregistered
swarm.health event.
Scope: this surfaces the diagnosis. Actually executing a run still requires the
deployment to set AGENT_LAUNCH_BACKEND=kubernetes AND the #16/#60 A.3 Pod Workload
Identity / KV grant (infra, cross-team) — called out in the launch note.
Tests (scripts/test-swarm-guard.py): blocked run emits timeline.updated exactly once
(dedup) + still no swarm.health; /result + /diagnostics carry health w/ no_agents_connected;
launch_swarm_agents records the backend=none note. test-contract-freeze + test-agent-launcher
still green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
