Table of Contents

Recover from an Implementation Crash

Learn how to restore a work package that is stuck in in_progress after an agent crash or process kill.

Detecting a Crash

A WP is stuck if:

  • Its lane is in_progress in status.events.jsonl but no agent is running
  • The worktree for the WP exists on disk but has no active process
  • spec-kitty doctor reports a stale claim

Run the health check:

spec-kitty doctor
# or restrict to a specific mission:
spec-kitty doctor --mission 034-my-feature

The output flags:

  • Stale claims — WPs in claimed for >7 days or in_progress for >14 days with no recent commits
  • Orphaned worktrees — worktrees that exist but all their WPs are in terminal lanes
  • Zombie locks — lock files left by a killed process

Restore Execution Context with --recover

The fastest path back to a working state is:

spec-kitty implement WP02 --recover

This command:

  1. Verifies the worktree exists and is on the correct branch
  2. Re-emits a claimed → in_progress transition (without creating a new worktree)
  3. Prints the workspace path so the agent can resume work

The --recover flag does not reset any code changes already committed in the worktree; it only repairs the status bookkeeping.

Full Recovery Steps

If --recover alone is not enough (e.g., the worktree is corrupt or the branch is missing):

Option A: Force WP back to planned and restart

# Reset status to planned (requires --force because in_progress is not a terminal lane)
spec-kitty agent tasks move-task WP02 --to planned --force --note "Recovery after crash"

# Delete the broken worktree manually if needed
git worktree remove .worktrees/034-my-feature-lane-a --force

# Re-run implement to get a fresh workspace
spec-kitty implement WP02

Option B: Continue in the existing worktree

# Confirm the worktree branch is clean enough to continue
cd .worktrees/034-my-feature-lane-a
git status

# Emit in_progress again to un-stale the claim
spec-kitty agent status emit WP02 --to in_progress --actor claude \
  --force --reason "Resuming after crash"

Using spec-kitty doctor

spec-kitty doctor (added in 3.1.0) summarises the full health of all missions in one pass:

Stale claims
  WP02  034-my-feature  in_progress  last event: 15 days ago

Orphaned worktrees
  .worktrees/033-old-feature-lane-a  all WPs done

No zombie locks found.

Address each finding before restarting implementation to avoid double-claiming a WP or writing to a dangling worktree.

See Also

Edit this page