pan-admin-cloister · diff
git:20260607.77744bf to git:20260918.7b95344
13 added, 32 removed. Audit A to A.
---
name: pan-admin-cloister
- description: "pan admin cloister <cmd> — lifecycle watchdog management: status, start, stop, freeze, unfreeze, brake, emergency-stop"
+ description: "pan admin cloister <cmd> — deacon-lite management: status, start, stop, emergency-stop"
triggers:
- pan admin cloister
- cloister status
- watchdog
- lifecycle watchdog
- emergency stop agents
allowed-tools:
- Bash
---
# pan admin cloister
- Manage the Cloister lifecycle watchdog — the daemon that monitors running agents,
- handles verification gates after completion, and triggers the review → test →
- ship specialist pipeline.
+ Manage deacon-lite — the surviving watchdog. It observes and nudges or
+ notifies; it never reconciles a stored copy of pipeline state. Its four
+ routines: nudge work agents idle too long with unpushed work, nudge agents
+ stuck on a repeated API error, reconcile the dashboard's agent-liveness
+ cache against the terminal backend's own inventory, and reap agents left
+ behind on closed issues.
## Usage
```
pan admin cloister status [--json] # Show watchdog service status and agent health
pan admin cloister start # Start the watchdog (no-op if already running)
pan admin cloister stop # Stop the watchdog (running agents continue)
- pan admin cloister freeze # Globally pause the Deacon — patrols fire but skip all actions
- pan admin cloister unfreeze # Resume the Deacon from a global pause
- pan admin cloister brake [--json] # Trim running WORK agents down to the concurrency cap (idle-first, resumable)
pan admin cloister emergency-stop # Kill ALL agents immediately — destructive
```
Stopping the watchdog does NOT stop running work agents — they continue in
- their tmux sessions. It only suspends the post-completion automation (verification
- gate, review/test/ship handoff). Restart with `pan admin cloister start` to
- re-engage automation.
-
- `freeze`/`unfreeze` are distinct from `start`/`stop`: freeze leaves the patrol
- timer running but short-circuits every cycle (no resumes, no review/test/ship
- dispatch, no recovery). The flag persists in `app_settings` across restarts and
- is read fresh each patrol, so it takes effect on the next tick. Use freeze when
- you want the watchdog process alive (status/logs still work) but all automatic
- action held — e.g. while landing changes that affect spawn behavior.
+ their sessions. It only suspends deacon-lite's own nudges and liveness
+ reconciliation. Restart with `pan admin cloister start` to re-engage it.
## When to use each subcommand
- - **`status`** — first stop for diagnosing why a completed agent didn't
- trigger review, or why a workspace seems stalled mid-pipeline.
+ - **`status`** — first stop for diagnosing why an idle agent wasn't nudged,
+ or why the dashboard's liveness view looks stale.
- **`start`** — after a host reboot, after `stop`, or when `pan status` shows
no watchdog process.
- **`stop`** — when debugging the watchdog itself, or when you want to make
- manual lifecycle interventions without the daemon racing you.
- - **`freeze`** — hold ALL automatic action (resumes + review/test/ship dispatch +
- recovery) while keeping the watchdog process alive. The go-to when you're
- changing spawn/concurrency behavior and don't want the deacon acting mid-change.
- - **`unfreeze`** — resume normal patrols after a `freeze`. Auto-resume and
- dispatch are bounded by the concurrency governor (`cloister.concurrency`).
- - **`brake`** — the *measured* alternative to `emergency-stop`. Stops only work
- agents **above** the configured concurrency cap (`cloister.concurrency.max_work_agents`),
- idle ones first, leaving them resumable so the deacon re-admits them as slots
- free. Use when the running count has drifted over the cap (forced `pan start`s,
- an unfreeze backlog) and you want to drain back to the limit without killing
- in-flight work. Non-destructive to source/git; review/test/ship are untouched.
+ manual lifecycle interventions without it racing you.
- **`emergency-stop`** — last resort. Kills every running agent (work, review,
- test, ship, planning). Workspaces and branches survive but tmux sessions
+ test, planning). Workspaces and branches survive but sessions
are destroyed. Use when something has gone catastrophically wrong (runaway
fork, memory exhaustion, billing alert).
## Confirm before emergency-stop
Treat `emergency-stop` like `pan wipe`: confirm with the user before invoking
it. It's not destructive to source or git state, but it terminates in-flight
work and the user will need to recover or restart agents.
## See also
- `pan admin specialists <cmd>` — manage review/test/ship specialist pool
- `pan recover <id>` — recover a crashed work agent
- `pan show <id> --health` — agent health and heartbeat
- `pan resources` — RAM/swap usage by agent
- `roles/work.md` — work-agent role definition