Troubleshooting

The failures that happen often enough to have an answer. Each one starts on the ticket’s Activity tab, which says what the run did and how it ended.

An agent says it is not signed in

Sign-in lives outside the app: every CLI owns a browser login that does not survive being driven from another process. Open Settings → Agents, press the help button on that row, run the command it shows in Terminal, then Check again. Herdloom marks a sign-in failure as not retryable, so the run did not burn its attempts; retry the ticket from the drawer once the row turns green.

A run stops with a usage limit

The CLI answered with its subscription’s limit before doing any work. The ticket parks in Needs you with the limit quoted, and the attempt is not counted against the project’s retries. Wait for the limit to reset, or open the drawer and hand the ticket to a different agent, then run it again.

A run stalls

No output for five minutes ends the run and parks the ticket. The usual cause is a command waiting for input that will never come. Read the last lines on the Activity tab: if the agent was mid-edit, retry and it starts fresh with the plan and the history of what failed. If it was stuck on a command, that command probably needs a non-interactive flag in the repository.

Verification keeps failing

Verification is two things: commits must exist on the branch, and the project’s test command must pass. Check Verification in project settings and run that command yourself in the main checkout. A suite that needs a database or a second service will fail in a worktree, because those are not started for you. If the tests are fine and the agent still cannot satisfy them, the plan was wrong rather than the code: use Plan again, not another retry. A circuit breaker parks the ticket early when two attempts change nothing.

A ticket parks with a conflict

Tickets within a work item run one at a time on the same branch. If another work item changes the base branch, use Update branch in the ticket drawer. Herdloom brings in the newer code and asks an agent to resolve conflicts if needed. If resolution still fails, open the preserved checkout in your editor, resolve and commit, then return to the work item to review and ship.

A pull request cannot be merged

The Merge button says what stands in the way rather than failing: a required review, checks that are failing or still running, a draft, a conflict. An administrator gets a separate Merge as admin where the ruleset allows bypass. Merge also refuses while a run is still active on the ticket.

A checkout is missing

A completed work item can have its clean checkout parked. An unfinished shared item keeps its checkout, including while paused or In PR. Independent ticket checkouts can also be reclaimed after returning to Backlog or when their PR branch is quiet. The branch remains available; restore the checkout from the Review tab when you want to run it again.

The board looks stale

A ticket imported from a tracker does not change when the issue changes: watches add tickets, they do not update them. Refresh in the drawer re-fetches one ticket. Triage results go stale the same way when you edit a ticket, so run triage again after a round of edits.

If nothing is moving at all, check three things: the agent is switched on in Settings → Agents, the project’s Queued limit is not already full, and the waiting tickets’ dependencies are actually Done. Autopilot never pulls from Backlog, so a card moved back there stays there on purpose.

Work-item checks and waiting tickets

One ticket runs while the others wait. Members share one checkout and run sequentially. Increase parallelism by making separate work items for independent changes, not by raising the limit on one bundle. Internal prerequisites need completed, verified code; external ones must land first.

The whole item is blocked. Expand it above the board and open the ticket marked Needs you. Answer its question, approve its plan, or resolve its failure. Pause the item if you need to set it aside. Never-started tickets can be returned to Backlog from the expanded paused item.

All tickets finished, but shipping is blocked. Every ticket must be ready and the checkout must be committed and idle. In the shipping dialog, Run the combined check first requires configured checks and the combined review to pass, with an enabled review agent. Read its findings and check again, or choose I’ve checked this myself if you have reviewed the result manually. Manual approval skips the combined check; Git conflicts and GitHub branch rules still apply.

A previous pass no longer applies. The code, requirements, membership, or relevant settings may have changed, or a check may have been interrupted. Recheck the current version. Use Stop check to cancel a running validation; cancellation preserves the work but does not authorize shipping.

See work items for the complete sequence.

Knowledge is being consulted again

Open Details → Knowledge on the ticket to inspect its saved findings and citations. From Ideas and From planning show where those findings came from. An approved plan does not necessarily include reusable knowledge findings.

Execution can request a new brief when findings are missing, requirements or attachments changed, or the source’s rules or relevant pages changed. Current findings are reused without another consultation. A specific page read during execution can also be the agent resolving a new question. Use Re-consult only when you want to request a fresh pass yourself.

Knowledge reuse explains each case.

Next

Feedback builds the report file to attach when none of this fits. Needs you explains the column these failures land in.