pan-kill · diff
git:20261002.48f5ddc to git:20261104.d7a9fc8
1 added, 1 removed. Audit A to A.
---
name: pan-kill
description: "pan kill <id> — stop a running agent (workspace and branch preserved)"
triggers:
- pan kill
- stop agent
- kill agent
- terminate agent
- abort agent
allowed-tools:
- Bash
- Read
---
# 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
```bash
# 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
```
- `<id>` also accepts `conv/<n>` or `conv:<n>` and a dashboard URL such as `https://overdeck.localhost/conv/2972` — a conversation target stops only that conversation, unlike an issue ID's issue-wide fan-out.
+ `<id>` also accepts a conversation name such as `20260928-7563`, `conv/<n>` or `conv:<n>` and a dashboard URL such as `https://overdeck.localhost/conv/2972` — a conversation target stops only that conversation, unlike an issue ID's issue-wide fan-out.
## Workflow
### 1. Check Agent Status First
```bash
pan status
pan show ISSUE-123
```
### 2. Graceful Shutdown (Recommended)
Give the agent a chance to save state:
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
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:
```bash
# 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