Recovering abandoned work

Applies to: Dispatch v1.0.0, last verified 2026-04-05

This guide shows you how to recover a stuck phase from start to finish: spot it in the Tasks view, read what the previous agent completed, reset the phase status, and start a fresh agent.

TL;DR: Switch to Tasks view, find the stalled phase, open the epic drawer to read the execution log, edit plan.md to reset the phase status to TODO, then start a new agent and point it at the phase.

When an agent runs out of context, loses its terminal, or crashes mid-phase, the phase stays stuck. The Tasks view surfaces it.

Step 1: Spot the abandoned phase

Open the center column and click Tasks (next to Epics) above the list.

The Tasks view shows every phase across all visible epics as a flat list. Phases are sorted so claimable ones appear first. Look for either of these patterns:

What you see	What it means
Phase status is `IN PROGRESS` with no live agent in the sidebar	The agent that claimed this phase is no longer running. The phase is stuck.
Phase status is `TODO` but the phase above it (earlier `id`) is `DONE`	The phase is ready to be claimed but no agent picked it up.

If the phase is IN PROGRESS with no live heartbeat for the assigned persona, that is your stuck phase.

Step 2: Understand what the previous agent completed

Click the epic card for the stalled epic (or click the epic name badge on the stuck phase row) to open the Epic Drawer.

The drawer shows two panels side by side:

Left panel: The full plan.md prose, with the context and objective the original planner wrote
Right panel: The execution-log.md, parsed into individual phase entries

Read the execution log entries for the phases before the stuck one. Each completed phase has an entry like this:

## [2026-04-03T14:32:00Z] Phase 2: Implement the API — @staff-engineer
Summary of what was done, findings, and handoff notes.

This tells you exactly what was finished, what decisions were made, and what the next phase needs to know. If Phase 3 is stuck, the Phase 2 entry is your handoff note.

If the stuck phase itself has a partial log entry (the agent started but didn’t complete), read that too. Partial entries can tell you how far the agent got before stopping.

Step 3: Reset the phase status

Open the plan.md file for the epic directly:

<project-root>/.tasks/<epic-name>/plan.md

Find the stuck phase in the YAML frontmatter. It looks like this:

phases:
  - id: 3
    title: "Write integration tests"
    persona: qa-engineer
    status: IN_PROGRESS

Change status: IN_PROGRESS to status: TODO:

phases:
  - id: 3
    title: "Write integration tests"
    persona: qa-engineer
    status: TODO

Save the file. Dispatch detects the change within seconds and updates the dashboard. The phase dot turns grey (todo), and the epic status updates to reflect the new state.

Step 4: Start a fresh agent

Open a new terminal in your project directory and start the agent assigned to that phase:

cd /path/to/your/project
claude --agent qa-engineer

The fresh agent will:

Scan .tasks/**/plan.md for phases matching its persona
Find Phase 3 (status: TODO, persona qa-engineer, prior phases DONE)
Read the execution log to pick up context from earlier phases
Claim the phase by editing status: TODO to status: IN_PROGRESS
Continue the work from where the previous agent stopped

On the dashboard you will see the phase dot turn blue (in progress) and the agent appear as live in the sidebar within a few seconds.

Step 5: Verify recovery

Watch the dashboard while the agent works:

The phase dot is blue and pulsing (in progress)
The agent sidebar shows the persona as live
When the agent finishes, the dot turns green and a new entry appears in the activity feed

If the phase is large and the agent again runs out of context before finishing, repeat this process. The execution log accumulates entries across multiple agent runs, so each fresh agent has the full history.

Common scenarios

The agent ran out of context

The most common cause. All LLM-based agents have a context window limit. On a large codebase or long phase, the agent reaches the limit and stops. The session JSONL stops being written, dispatch’s reactor sees the stall and after 5 minutes of inactivity may close the phase to DONE with closedReason: 'no-active-session'. If the phase still shows IN_PROGRESS, the YAML may not yet have been touched by the reactor — restart the agent or reset the status manually.

Recovery: reset to TODO as described above. The fresh agent will pick up from the execution log context.

The terminal was closed

If someone closed the terminal window or the machine was rebooted, the session JSONL stops being written and the phase stays stuck. Same recovery path.

The agent marked itself BLOCKED

If a phase shows BLOCKED, the agent ran into something it could not resolve on its own. Open the epic drawer and read the execution log entry for that phase. The agent should have written an explanation of what blocked it.

To unblock: resolve the dependency the agent described, then change the phase status from BLOCKED back to TODO and restart the agent.

Multiple phases are stuck

If several phases across different epics are stuck, the Tasks view shows them all. Work through them one at a time, starting with the ones that are blocking other phases. Phases with IN PROGRESS status block later phases in the same epic from being claimed.

Preventing future stuck phases

The .tasks/ protocol has a soft lock mechanism. When an agent claims a phase, it edits the frontmatter from TODO to IN_PROGRESS. If the agent dies before finishing, no automatic cleanup happens and the lock stays. This is by design: automatic unlocking would risk two agents working the same phase simultaneously.

To minimize stalls:

For long phases, ask the agent to write partial execution log entries as it progresses. This gives more context for the recovery agent.
Check the Tasks view before starting a new planning session. If prior phases are stuck, recover them before planning new ones on top.