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

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:

liza recover-task <task-id>

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:

liza recover-task <task-id> --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:

liza recover-agent <agent-id>

This releases the agent’s claim, removes its worktree, and deletes the agent from state. Then restart the agent manually:

liza agent coder --agent-id coder-1

Or recover and respawn in one step:

liza recover-agent coder-1 --cli claude

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:

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:

liza release-claim <task-id>

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:

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:

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:

   liza release-claim <task-id>
   

2. If no live agent exists to pick up the released work, spawn agents for all claimable roles that have no live agent:

   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:

liza get tasks --status blocked
liza get tasks <task-id>     # 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:

   liza unblock-task <task-id> --reason "Resolved: [explanation]"
   

4. To resume directly on a specific agent (fast path):

   liza unblock-task <task-id> --reason "..." --assign-to coder-1
   

5. If the orchestrator has assessed the blocker and cannot resolve it, record the triage:

   liza assess-blocked <task-id>
   

   This raises an UNRESOLVED BLOCKED alert so you have a clear audit trail.

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:

liza unblock-task <task-id> --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:

liza get tasks <task-id>     # Confirms INTEGRATION_FAILED status
cd .worktrees/<task-id>
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:

   liza claim-task <task-id> coder-2
   

2. Resolve the conflicts in the worktree:

   cd .worktrees/<task-id>
   # Edit conflicted files
   git add .
   git commit -m "Resolve integration conflict"
   

3. Resubmit for review:

   cd ../..
   liza submit-for-review <task-id> 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):

liza reconcile-merged <task-id>

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:

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:

   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.

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:

liza get agents              # Check process_status, process_status_source, lease_expires
liza validate                # Flags mismatched agents

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:

liza recover-agent <agent-id>
# or
liza delete agent <agent-id>

​

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:

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-<provider> exists.

Diagnosis:

ls .liza/provider-quota-exhausted-*
cat .liza/alerts.log | grep "PROVIDER QUOTA"

Fix:

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:

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

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 <task-id>
Crashed agent (by agent)	liza recover-agent <agent-id>
Stale lease	liza release-claim <task-id>
Stale review leases (all)	liza clear-stale-review-claims
No live agent for claimable work	liza repair-agent-pool
BLOCKED task	liza unblock-task <task-id> --reason "..."
Integration failure	Claim → resolve → liza submit-for-review <task-id>
Circuit breaker tripped	Fix root cause → liza resume
Ghost agent	liza recover-agent <agent-id>
Orphaned worktree	liza wt-delete <task-id>
Validate state	liza validate
Pattern analysis	liza analyze