Failure recovery

AgentFlow persists explicit task states instead of implying progress from stray files. Recovering cleanly means respecting those transitions—or using documented overrides (--force, resume helpers) where the orchestrator allows retries.

State machine

Tasks move through explicit statuses enforced in workflow/state_machine.go:

stateDiagram-v2
  [*] --> pending
  pending --> planned
  planned --> enriched
  enriched --> running
  running --> implemented
  implemented --> verified
  verified --> reviewed
  reviewed --> ready_for_pr
  running --> failed
  implemented --> verify_failed
  verified --> review_failed
  verify_failed --> implemented
  review_failed --> verified

Invalid transitions return errors unless --force is allowed on the specific command.

Common recoveries

The recipes below mirror how teams unwind the most frequent stuck states once local fixes land in the worktree tied to that task.

Verify failed

# fix code in worktree, then:
agentflow verify billing-v2 --force

Review failed

agentflow review billing-v2 --agent codex --force

Interrupted run

agentflow status
agentflow resume <run-id>          # prints next step: plan|enrich|dev|verify|review
agentflow continue "resume billing-v2"   # intent-based continuation

Clean stale worktrees

agentflow clean

Removes worktrees according to worktrees.cleanup_policy (keep_failed keeps failed task trees).

Reports for post-mortems

When someone needs breadcrumbs after the fact—or you are reconciling timelines with reviewers—persisted run metadata is surfaced through report and cross-feature investigate summaries.

agentflow report <run-id>
agentflow investigate billing-v2

Related

• Worktree isolation
• CLI: resume
• CLI: continue