Every task's records live in its run folder, so you can always read what a model actually said. Start with the status.
Task statuses
Status
What it means, and what to do
FAIL
A blocking finding. Retry with the findings, maybe on a stronger model.
UNKNOWN
No verdict. A retry asks the reviewer again on the same work; no dwarf runs, no attempt is spent.
INVALIDATED
The reviewer edited a tracked file in its copy, so its verdict counts for nothing. Retry reviews the unchanged work.
INFRA
A provider problem: rate limit, quota, sign-in, network, or a CLI that cancelled its own session (grok does at a command it can't approve headless). No attempt spent. If it says "needs you", log in or add credits; otherwise run the same command again, or use --infra-retries.
TIMEOUT
A model ran past the limit. Raise --timeout, or retry; partial work is in the worktree.
CONFLICT
Review passed but the merge conflicted, usually a file the task didn't declare. The scope-drift list names it.
ERROR
A worktree or dispatch failed. Read tasks/<id>/dwarf.out or qa.out.
NEEDS_DECISION
The retry policy stopped, or every blocking finding needs a file another task owns. tasks/<id>/decision.md lists the choices. Decide with forge control retry --decide; see Steering.
NEEDS_INPUT
The task asked you a question. Answer it with retry --answer, or in forge-ui's task panel.
STALE
Its prompt changed while the attempt ran. Not reviewed, no attempt spent; the dwarf runs again with the new text.
Surprising results
What happened
Why, and the fix
Merged although the reviewer said FAIL
Every finding was milder than the threshold, so it passed with known issues, listed in known_issues.md.
Failed although the reviewer said PASS
It listed a confirmed finding at the threshold or worse. forge goes by the findings.
The dwarf produced no changes
Usually a goal it couldn't settle alone. Make it more specific, or turn on brief mode.
Several tasks produced nothing
The split made tasks that can't stand alone. Use a coarser --decompose-level.
Every wave has one task
Most tasks share files. Split the goal differently.
Pieces don't fit together
The shared interface was never agreed. Plan first, or use --planner.
FLAKY with a passing verification
The check failed once and passed on rerun. Read verification.log; it can be a real bug.
Reviews say their tests couldn't run
The reviewer's sandbox lacked something. The run summary lists those reviews; check the dependency or the verify command.
Installation
Problem
Fix
/forge missing in a CLI
Run forge install again and restart the session.
Antigravity runs an old version
It copies forge's files. Run forge install after every update.
Antigravity dwarf ends with an empty diff
It tried a shell command without --yolo-dwarf; one refusal ends its run.
OpenCode shows forge twice
It finds forge in ~/.claude/ on its own. Remove the extra copy.
Recovering
An interrupted run isn't lost: run the same run again. Merged tasks are skipped.
A failed task is cheap to redo: retry reuses its worktree and findings.
"Already exists" on retry means a worktree folder was deleted by hand. Run the command again rather than deleting the branch.