Stop Agent

Overview

pan kill (alias pan stop) stops an agent and closes its terminal through the host's terminal
backend: pane.close on Herdr (the default), kill-session on tmux. The workspace, branch, and
xBRIEF are preserved.

Always stop agents with pan kill, never with raw tmux kill-session or herdr pane close. A raw
terminal kill skips the state write, the orphan-launcher sweep, and the Docker teardown; a raw tmux
kill on a Herdr host reaches nothing at all (PAN-3947).

When to Use

• Agent is stuck or not making progress
• Need to reassign the work
• Agent completed work and should be stopped
• Emergency stop needed
• Freeing up system resources

Quick Command

# Every agent of an issue (work, planning, review/test specialists, strike, swarm slots)
pan kill ISSUE-123

# Exactly one agent
pan kill agent-issue-123-test

Workflow

1. Check Agent Status First

pan status
pan show ISSUE-123

2. Graceful Shutdown (Recommended)

Give the agent a chance to save state:

# ALWAYS use pan tell, never raw send-keys
pan tell ISSUE-123 "Please commit your progress and stop working."

# Then stop it
pan kill ISSUE-123

3. Verify Stopped

# alive comes from the host backend (Herdr or tmux); tmuxActive is tmux-only and deprecated
pan status --json | jq -r '.[] | select(.issueId == "ISSUE-123") | "\(.id) alive=\(.alive)"'

Every agent of the issue must read alive=false. If one does not, see Troubleshooting.

Pause Instead of Kill

pan pause ISSUE-123 --reason "<why>" stops the agent the same way and also sets a persistent
pause gate so nothing restarts it until pan unpause ISSUE-123.

Kill All Agents

Use /pan-stop-all-agents — it drains every work agent and its specialists while preserving
conversations and shared sidecars.

Preserving Work

# Preserve workspace state (per stash-discipline: agents commit or surface; never stash)
cd /path/to/workspaces/feature-issue-123
git add -A && git commit -m "WIP: state before kill"

After Killing

1. Resume later — pan start ISSUE-123 spawns a new agent
2. Do it yourself — work in the existing workspace manually
3. Abandon — remove the workspace if the work is no longer needed

Troubleshooting

Agent still alive after pan kill: the terminal did not close. List the live panes the
dashboard sees on the host's backend:

curl -s http://localhost:3011/api/agents \
  | jq -r '.[] | select(.issueId == "ISSUE-123" and .hasLiveTmuxSession == true) | "\(.id) pane=\(.paneState)"'

/api/agents caches for about 5 seconds, so wait that long after a kill before trusting it.
Then run pan kill <agent-id> again. If it still survives, find the pane on the backend itself:

# Herdr host: panes carry the agent id in their agentId token
herdr pane list

# tmux host, or a pre-Herdr agent still on tmux: the overdeck socket, never the default one
tmux -L overdeck list-sessions | grep -i issue-123

Close a pane by hand only if the backend is unreachable from pan, and report it as a bug.

Related Skills

• /pan-status — check agent status
• /pan-tell — send a message before killing
• /pan-pause — stop and hold an agent