stevengonsalvez/swarm-shutdown

/swarm-shutdown

Gracefully shutdown a swarm team with optional force flag.

Usage

/swarm-shutdown <team-id> [--force]

Arguments

| Argument | Required | Description | |----------|----------|-------------| | <team-id> | Yes | The swarm team ID to shutdown | | --force | No | Skip graceful shutdown, kill immediately |

Process

When you receive this command:

Graceful Shutdown (Default)

1. Broadcast Shutdown Message

   source {{HOME_TOOL_DIR}}/utils/swarm-lib.sh
   
   echo "Initiating graceful shutdown of $TEAM_ID..."
   
   # Notify all agents
   swarm_broadcast "$TEAM_ID" "system" "shutdown" \
     '{"reason": "graceful shutdown requested", "checkpoint": true}'
   
   echo "Shutdown message broadcast to all agents"
   

2. Wait for Checkpoint

   echo "Waiting 10 seconds for agents to checkpoint..."
   sleep 10
   

3. Verify Agent Status

   # Check if agents have acknowledged
   TEAM_DIR="{{HOME_TOOL_DIR}}/swarm/$TEAM_ID"
   
   for inbox in "$TEAM_DIR"/inbox/*.jsonl; do
     AGENT=$(basename "$inbox" .jsonl)
     LAST_MSG=$(tail -1 "$inbox" 2>/dev/null | jq -r '.type' || echo "")
   
     if [ "$LAST_MSG" = "checkpoint" ]; then
       echo "  + $AGENT checkpointed"
     else
       echo "  o $AGENT (no checkpoint confirmation)"
     fi
   done
   

4. Kill tmux Sessions

   TEAM_JSON=$(cat "$TEAM_DIR/team.json")
   
   # Kill leader
   LEADER_SESSION=$(echo "$TEAM_JSON" | jq -r '.leader.session')
   if tmux has-session -t "$LEADER_SESSION" 2>/dev/null; then
     tmux kill-session -t "$LEADER_SESSION"
     echo "  + Killed leader: $LEADER_SESSION"
   fi
   
   # Kill agents
   for session in $(echo "$TEAM_JSON" | jq -r '.members[].session'); do
     if tmux has-session -t "$session" 2>/dev/null; then
       tmux kill-session -t "$session"
       echo "  + Killed agent: $session"
     fi
   done
   

5. Update Team State

   swarm_update_team "$TEAM_ID" '{"status": "shutdown", "shutdown_at": "'"$(date -Iseconds)"'"}'
   

6. Report

   echo ""
   echo "========================================"
   echo "  Swarm Shutdown Complete: $TEAM_ID"
   echo "========================================"
   echo ""
   echo "  Team data preserved at:"
   echo "    $TEAM_DIR/"
   echo ""
   echo "  To archive: /swarm-archive $TEAM_ID"
   echo "  To restart: /swarm-create with same epic"
   echo ""
   

Force Shutdown (--force)

Skip the graceful steps and kill immediately:

echo "Force shutdown of $TEAM_ID..."

# Kill all sessions without waiting
swarm_shutdown "$TEAM_ID" --force

echo "Force shutdown complete"

Output

Graceful Shutdown

================================================================
  SWARM SHUTDOWN: swarm-1738585396
================================================================

Phase 1: Broadcasting shutdown...
  -> Sent to leader
  -> Sent to agent-1
  -> Sent to agent-2
  -> Sent to agent-3

Phase 2: Waiting for checkpoints (10s)...
  ==================== 100%

Phase 3: Verifying checkpoints...
  + leader: checkpointed
  + agent-1: checkpointed
  + agent-2: checkpointed
  o agent-3: no response (will force kill)

Phase 4: Terminating sessions...
  + Killed: swarm-1738585396-leader
  + Killed: swarm-1738585396-agent-1
  + Killed: swarm-1738585396-agent-2
  + Killed: swarm-1738585396-agent-3

Phase 5: Updating team state...
  + Status set to: shutdown

================================================================
  SHUTDOWN COMPLETE
================================================================

  Team data preserved at: {{HOME_TOOL_DIR}}/swarm/swarm-1738585396/

  Options:
    Archive team:    swarm-lib.sh archive swarm-1738585396
    View final state: cat {{HOME_TOOL_DIR}}/swarm/swarm-1738585396/team.json
    Restart:         /swarm-create --epic bd-epic-123

================================================================

Force Shutdown

================================================================
  FORCE SHUTDOWN: swarm-1738585396
================================================================

Killing sessions immediately...
  + Killed: swarm-1738585396-leader
  + Killed: swarm-1738585396-agent-1
  + Killed: swarm-1738585396-agent-2

Status updated to: shutdown

================================================================

Agent Checkpoint Protocol

When agents receive a shutdown message, they should:

1. Complete or Pause Current Work

   • If close to completion: finish the task
   • Otherwise: save progress state

2. Update Beads

   # Mark task as paused/blocked
   bd update $CURRENT_TASK --status blocked --reason "Swarm shutdown"
   

3. Send Checkpoint Confirmation

   swarm_send_message "$TEAM_ID" "$AGENT_NAME" "system" "checkpoint" \
     '{"task": "'"$CURRENT_TASK"'", "progress": 75, "state": "saved"}'
   

4. Clean Up

   • Close any open files
   • Save session notes to shared/

Post-Shutdown Options

Archive Team

# Move team to .archive/ directory
swarm-lib.sh archive swarm-1738585396

Delete Team

# Permanently remove team data
rm -rf {{HOME_TOOL_DIR}}/swarm/swarm-1738585396

Restart Team

# Create new swarm from same epic
/swarm-create --epic bd-epic-platform-rebuild --agents 3

Error Handling

| Error | Resolution | |-------|------------| | Team not found | Verify team ID exists | | Sessions already dead | Proceeds with state update only | | Permission denied | Check tmux socket permissions | | Checkpoint timeout | Force flag used automatically after timeout |