> ## Documentation Index > Fetch the complete documentation index at: https://lizamas.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # How to Recover from Crashed Agents and Stuck Tasks > Liza provides recovery commands to handle crashed agents, stale leases, stuck tasks, integration failures, and circuit breaker trips without losing work. Liza is designed for resilience. Agent crashes, stale leases, integration conflicts, and circuit breaker trips are all recoverable without losing the work already done. Most failures follow a recognizable pattern: identify the symptom using diagnostic commands, apply the appropriate recovery command, and resume. This guide walks through each failure scenario and the exact steps to resolve it. ## Diagnostic Commands Run these commands first when something looks wrong. They give you the information you need to pick the right recovery action. | Command | What It Shows | | - | - | | `liza status` | Dashboard: goal, sprint state, agent states, task summary, phase-handoff blockers | | `liza get tasks` | All tasks with current state, assignments, lease expiry | | `liza get tasks --format table` | Compact tabular view | | `liza get tasks --status blocked` | Blocked tasks only | | `liza get agents` | Registered agents and lease status | | `liza get agents --zombies` | Live agent processes missing from state | | `liza validate` | Check blackboard state against schema invariants | | `liza analyze` | Circuit breaker pattern detection | > [!TIP] > > Agent logs in `.liza/agent-outputs/` are your primary deep-dive tool. Run `/liza-logs` in any pairing agent session to cross-correlate logs across agents, diagnose patterns, and get proposed fixes. ## Crashed Agent Recovery **Symptom:** An agent exits unexpectedly mid-task. The task remains in an executing state with a stale lease. **Diagnosis:** Run `liza get agents` and check `process_status`. A dead process with an active lease indicates a crashed agent. ### Recover by Task ID Use this when you know which task the agent was working on: ```bash theme={null} liza recover-task ``` This releases the agent's claim and reattaches a coherent worktree and branch when possible, preserving any work the agent completed before crashing. Run `liza status` afterwards to confirm the task returns to a claimable state. To explicitly discard the worktree and reset the task to its initial state: ```bash theme={null} liza recover-task --fresh ``` Use `--fresh` when the worktree is corrupted or you want a clean restart on the task. ### Recover by Agent ID Use this when you know the agent ID and want full cleanup: ```bash theme={null} liza recover-agent ``` This releases the agent's claim, removes its worktree, and deletes the agent from state. Then restart the agent manually: ```bash theme={null} liza agent coder --agent-id coder-1 ``` Or recover and respawn in one step: ```bash theme={null} liza recover-agent coder-1 --cli claude ``` > [!NOTE] > > Both `recover-task` and `recover-agent` are idempotent — safe to run multiple times. Use `--force` if the agent's PID is still alive and you want to bypass live-PID checks. ## Stale Lease **Symptom:** A task is stuck in an executing or reviewing state, but the agent is gone or unresponsive. The lease expiry timestamp is in the past. **Diagnosis:** ```bash theme={null} liza get tasks # Check lease_expires field liza validate # Flags tasks with expired leases ``` Lease defaults: 30-minute duration, 60-second heartbeat interval. If `lease_expires` is in the past, the task is stale. **Fix:** ```bash theme={null} liza release-claim ``` This releases the claim without touching the worktree. The task returns to a claimable state and the next available agent picks it up. To release an expired review lease specifically: ```bash theme={null} liza clear-stale-review-claims ``` ## Stuck Task **Symptom:** A task is stuck in IMPLEMENTING or REVIEWING with no visible progress. No lease expiry issue — the agent is registered but appears stalled. **Diagnosis:** ```bash theme={null} liza status liza get tasks --format table liza get agents # Check agent status field ``` Look at the agent's `status` field: WORKING means it is active; WAITING or HANDOFF may indicate a stall. **Fix:** 1. Release the claim to free the task: ```bash theme={null} liza release-claim ``` 2. If no live agent exists to pick up the released work, spawn agents for all claimable roles that have no live agent: ```bash theme={null} liza repair-agent-pool ``` Add `--cli claude` (or another provider) to specify which CLI to use for newly spawned agents. Add `--dry-run` to preview the spawn commands without executing them. ## BLOCKED Task **Symptom:** A task is in BLOCKED state. Agents skip it. The task has a `blocked_reason` and `blocked_questions` set. **Diagnosis:** ```bash theme={null} liza get tasks --status blocked liza get tasks # Shows blocked_reason and blocked_questions ``` Agents self-block when they hit a decision they cannot make — a spec gap, a missing dependency, or a question that requires product input. **Fix:** 1. Read the `blocked_reason` and `blocked_questions` fields carefully. 2. Answer the questions in the spec or in the task's context. 3. Unblock the task: ```bash theme={null} liza unblock-task --reason "Resolved: [explanation]" ``` 4. To resume directly on a specific agent (fast path): ```bash theme={null} liza unblock-task --reason "..." --assign-to coder-1 ``` 5. If the orchestrator has assessed the blocker and cannot resolve it, record the triage: ```bash theme={null} liza assess-blocked ``` This raises an `UNRESOLVED BLOCKED` alert so you have a clear audit trail. > [!NOTE] > > If the blocked task has a preserved worktree and the integration branch has moved while it was blocked, rebase it as part of the unblock: > > ```bash theme={null} > liza unblock-task --rebase-on integration --reason "..." > ``` > > Add `--allow-dirty` if the worktree has tracked changes that need autostashing during the rebase. ## Integration Failure **Symptom:** A task moves to INTEGRATION\_FAILED. A merge conflict or test failure occurred when Liza tried to merge the approved work into the integration branch. **Diagnosis:** ```bash theme={null} liza get tasks # Confirms INTEGRATION_FAILED status cd .worktrees/ git status # Shows conflicted files ``` The task worktree is preserved automatically for conflict resolution. **Fix:** 1. Any coder agent can claim the task for conflict resolution: ```bash theme={null} liza claim-task coder-2 ``` 2. Resolve the conflicts in the worktree: ```bash theme={null} cd .worktrees/ # Edit conflicted files git add . git commit -m "Resolve integration conflict" ``` 3. Resubmit for review: ```bash theme={null} cd ../.. liza submit-for-review HEAD --agent-id coder-2 ``` The task goes through the full review cycle again before merging. If the conflict was resolved externally (outside Liza's worktree workflow): ```bash theme={null} liza reconcile-merged ``` > [!TIP] > > Prevent integration failures by keeping task scope small and merging the integration branch into task branches frequently during long implementations. ## Circuit Breaker Tripped **Symptom:** `liza tui` or `liza analyze` reports a circuit breaker pattern. The system mode is `CIRCUIT_BREAKER_TRIPPED`, the sprint is at CHECKPOINT, and all agents have halted. **Diagnosis:** ```bash theme={null} liza analyze cat .liza/circuit_breaker_report.md cat .liza/sprint_summary.md ``` Circuit breaker patterns indicate a systemic issue — not a single agent failure, but a recurring failure mode that points to a root cause in the spec, architecture, or environment. | Pattern | Severity | What It Indicates | | - | - | - | | `retry_cluster` | ARCHITECTURE\_FLAW | A design issue being repeatedly hit | | `debt_accumulation` | SCOPE\_FLAW | Too many workarounds accumulating | | `assumption_cascade` | SPEC\_FLAW | A wrong assumption propagating through tasks | | `spec_gap_cluster` | SPEC\_FLAW | An ambiguous spec causing repeated agent questions | | `workaround_pattern` | ARCHITECTURE\_FLAW | A root cause being patched repeatedly | | `external_service_outage` | EXTERNAL\_DEPENDENCY | An external service is unavailable | **Fix:** 1. Read the circuit breaker report to understand the pattern and evidence. 2. Fix the root cause — update the spec, fix the architecture, resolve the external dependency, or amend the goal document. 3. Commit your changes. 4. Resume to clear the circuit breaker and restart the sprint: ```bash theme={null} liza resume ``` After clearing, `liza analyze` will show `status: OK` and `current_trigger: null`. Historical anomalies from before the clear are acknowledged and excluded from future pattern detection. > [!WARNING] > > Do not resume without fixing the root cause. The circuit breaker will trip again on the same pattern, and the anomaly history will continue to grow. ## Ghost Agent **Symptom:** An agent is registered in state but its process is dead or the registered PID belongs to a different process. **Diagnosis:** ```bash theme={null} liza get agents # Check process_status, process_status_source, lease_expires liza validate # Flags mismatched agents ``` > [!NOTE] > > On Linux, Liza uses procfs identity checks to distinguish a live Liza supervisor from a dead or PID-reused process. In containers or across SSH boundaries, a live host agent can appear as `process_status: stopped` because its PID is not visible from the current namespace. Do not recover based on `process_status: stopped` alone in those environments — check recent heartbeat and active lease as stronger liveness evidence. **Fix:** ```bash theme={null} liza recover-agent # or liza delete agent ``` ## Zombie Agent Process **Symptom:** A live `liza agent` process is running but is not registered in state. It can collide with registered agents by claiming the same work. **Diagnosis:** ```bash theme={null} liza get agents --zombies liza validate ``` **Fix:** Inspect the PID and stop the stale process manually. Then run `liza repair-agent-pool` to spawn clean replacements. ## Provider Quota Exhausted **Symptom:** All agents using a provider have stopped. The system mode is still RUNNING. A signal file `.liza/provider-quota-exhausted-` exists. **Diagnosis:** ```bash theme={null} ls .liza/provider-quota-exhausted-* cat .liza/alerts.log | grep "PROVIDER QUOTA" ``` **Fix:** ```bash theme={null} liza pause liza resume # Clears quota signals and restarts the sprint ``` Run `liza pause` first — `liza resume` alone fails because the system is still RUNNING, not PAUSED. ## Full State Reset (Last Resort) Use this only when the state is unrecoverably corrupted and you want to start fresh on the same goal: ```bash theme={null} liza stop # Back up state for audit cp .liza/state.yaml .liza/state.yaml.bak # Remove blackboard and re-initialize rm -rf .liza liza init "Your goal" --spec path/to/your-goal.md ``` > [!WARNING] > > A full state reset discards all sprint history, task state, and agent logs. Back up `.liza/` before proceeding. Prefer targeted recovery commands over a full reset whenever possible. ## Quick Reference | Scenario | Command | | - | - | | Crashed agent (by task) | `liza recover-task ` | | Crashed agent (by agent) | `liza recover-agent ` | | Stale lease | `liza release-claim ` | | Stale review leases (all) | `liza clear-stale-review-claims` | | No live agent for claimable work | `liza repair-agent-pool` | | BLOCKED task | `liza unblock-task --reason "..."` | | Integration failure | Claim → resolve → `liza submit-for-review ` | | Circuit breaker tripped | Fix root cause → `liza resume` | | Ghost agent | `liza recover-agent ` | | Orphaned worktree | `liza wt-delete ` | | Validate state | `liza validate` | | Pattern analysis | `liza analyze` | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.