swarm-observer

# Swarm Observer Monitor any `agent-toolkit swarm` run, diagnose stuck handoffs or backend drift, and recover without losing windows. Works for both **Herdr** (tabs) and **tmux** (isolated socket `agent-toolkit-swarm-<run-id>`). Integrates with swarm's eager-window model (every role starts as `Waiting for handoff: <pred> -> <role>` with `agent_waiting` trace). ## When to use - A swarm was launched and the user asks "is it done?", "what's the status?", "show logs", or "attach". - A handoff has been `active` for >5m (`955be6f6e2c...` pattern) or `worktree_failed`. - Herdr shows extra workspaces (`w7-wA`) for `headless` runs — the `get_backend("headless")` fallback case. - User wants to reuse the same run for a new request and needs to know if windows are still alive. ## Prerequisites - Run lives under `.agent-toolkit/swarm/runs/<run-id>/state.json` (filesystem is authoritative). - Know `run-id` (`20260807T...-xxxxxx`) from `swarm start --json` or `swarm list --json`. - Shell is detected (`_user_shell()`: `$SHELL` → `pwd.getpwuid` → `/usr/bin/zsh` fallback, executed as `<shell> -lc`). ## Workflow ### 1. List and pick the run ```bash agent-toolkit swarm list --json | jq agent-toolkit swarm status --run-id <run-id> agent-toolkit swarm status --run-id <run-id> --json | jq '.handoffs,.worktrees,.trace' ``` ### 2. Inspect handoffs and trace ```bash agent-toolkit swarm handoffs --run-id <run-id> agent-toolkit swarm handoffs --run-id <run-id> --json | jq '.[] | {id,from,to,st...