pan-untroubled · diff
git:20260522.817c2c7 to git:20260926.88caa70
9 added, 11 removed. Audit A to A.
---
name: pan-untroubled
- description: "pan untroubled <id> — clear an agent troubled gate and failure counters without spawning it"
+ description: "pan untroubled <id> — clear an agent troubled gate without spawning it"
triggers:
- pan untroubled
- - clear troubled agent
- - reset failure counter
- - clear crash loop
+ - untroubled agent
+ - clear troubled gate
+ - agent is troubled
allowed-tools:
- Bash
- Read
---
# pan untroubled
Run the command now:
```bash
pan untroubled <issue-id>
```
## Usage
```bash
pan untroubled PAN-123
```
## What It Does
- `pan untroubled <id>` clears the troubled gate and accumulated failure tracking fields from the agent state file. It does not spawn or resume the agent immediately.
+ `pan untroubled <id>` clears the troubled flag and its accumulated failure-tracking fields (consecutive failures, first/last failure timestamps, last failure reason) from the agent state file. It does not resume or spawn the agent — a repeatedly crashing agent should restart only when the operator chooses to. After clearing, it prints `pan start <id>` for the operator to run next.
- After the troubled gate is clear, the Deacon's next patrol can auto-resume the agent if it is otherwise eligible. If the operator wants the agent running right away, run `pan start <id>` after clearing the gate.
+ An agent becomes troubled after three consecutive resume/start failures within ten minutes. While troubled, `pan start`, `pan resume`, dashboard Start, and MERGE all refuse until the gate is cleared.
## When to Use
- - Use `pan untroubled` only after investigating and fixing the cause of repeated crashes or resume failures.
- - Use `pan unpause <id>` for a manual pause gate; it does not clear failure counters.
- - Use `pan kill <id>` when you only need to stop a currently running session.
+ - Use `pan untroubled <id>` after investigating the crash cause, to clear the gate without starting the agent yet.
+ - Use `pan start <id> --force` instead only when you intentionally want to clear the troubled gate and spawn in one step.
## See Also
- - `pan status` — check whether an agent is paused, troubled, stopped, or running
+ - `pan unpause <id>` — clear the separate pause gate (unrelated flag, same shape of command)
- `pan start <id>` — spawn after the gate is clear
- - `pan pause <id>` — intentionally suppress auto-resume