Troubleshooting the first run

The quickstart shows the happy path. This page covers the branches that are not failures of your setup so much as normal first-run friction: a missing worker runtime, a guarded start, a long silent phase, an interruption, a rejected gate, or a diff that is not where you expected it.

Each section starts from what you see, not from internals.

A worker runtime is missing or not authenticated

What you see. A phase fails almost immediately, and the error mentions the runtime command (claude, codex, gemini) or an authentication problem. Orcho does not retry authentication failures — the run stops so you can fix access once instead of burning attempts.

Why. Orcho invokes a code-agent CLI for each phase. If the selected runtime is not on PATH, or its CLI is installed but not logged in, the phase cannot start.

What to do. Check the runtime the failing phase selected:

claude --version
claude auth status

codex --version
codex login status

Either install and authenticate that CLI, or route the phases to a runtime you already have. One installed runtime is enough: the phases block in config.local.json maps every phase to a runtime id. Quickstart step 2 has the canonical snippet.

The run halts before starting: dirty checkout

What you see. Before any phase runs, Orcho stops with a Pre-run intake prompt listing four choices.

Why. Your project checkout already contains uncommitted changes. This is a guard, not an error: Orcho refuses to silently mix previous edits, the new task, and future evidence into one unreadable pile. You decide whether the existing work belongs to this run.

What to do. Pick the choice that matches your intent:

Choice	Effect
`include`	Seed the isolated run with the current diff.
`exclude`	Start from `HEAD`; leave checkout changes untouched.
`commit`	Commit the current checkout first, then run.
`halt`	Stop before the run starts.

Run lifecycle explains why intake exists and how the same principle returns at delivery time.

The run seems stuck

What you see. A phase has printed nothing for a while.

Why. Worker agents take minutes per phase, not seconds — a feature-shaped run takes tens of minutes. Silence during implement or review_changes is usually work, not a hang. Two timeout families bound the wait: a hard wall-clock cap per runtime (claude_seconds, env CLAUDE_TIMEOUT, and the codex / gemini equivalents) and an idle watchdog that resets whenever the worker streams output (claude_idle_seconds, env CLAUDE_IDLE_TIMEOUT). See Configuration reference.

What to do. Run with --output live to watch the agent transcript instead of guessing. And if you decide to kill the process: that is safe. The run becomes recorded, resumable state — completed phases stay completed, and orcho run --resume continues from the checkpoint. Nothing is lost. See Recovery and resume.

I interrupted it, or my terminal died

What you see. The process is gone; you are not sure what state the run is in.

Why. Runs are recorded state on disk, so an interrupted process leaves a resumable run, not a corpse.

What to do. Check state first, then resume:

orcho status
orcho run --resume 20260628_125026

Bare orcho run --resume picks the most recent run. Two special cases:

If status shows awaiting_phase_handoff, the run was paused on a decision before the interruption. Decide the handoff first, then resume. Handoffs and advisors lists the actions.
If the state looks torn or inconsistent, diagnose it with orcho repair-state <run-id>. Dry-run is the default and writes nothing; add --apply only after reading the proposed repair.

Review or final acceptance rejected, and I do not understand why

What you see. The run pauses or ends with a rejected verdict from review_changes or final_acceptance.

Why. A gate found something. The verdict is backed by concrete findings — the point of the lifecycle is that “rejected” always comes with reasons you can read.

What to do. Read the findings before deciding anything:

orcho evidence --format md

Then pick the honest action at the handoff: retry_feedback with a concrete correction when the finding should be fixed, or continue_with_waiver only when you intentionally accept the risk — the waiver text is recorded durably. Do not use continue as a way to avoid reading the findings. Handoffs and advisors covers each action.

git diff shows nothing, or shows unexpected changes

What you see. After the run, git diff in your project is empty — or shows changes you did not expect.

Why. Changes reach your checkout only through the delivery decision at the end of the run, never as a side effect of implementation. The interactive default is apply: the diff lands in your checkout uncommitted, as a draft for review — that is the “unexpected changes” case working as designed. If you chose skip, the diff stays in the run’s retained artifacts and your checkout is untouched — that is the “nothing” case.

What to do. Inspect the retained patch without applying it:

orcho diff 20260628_125026 --preview
orcho diff 20260628_125026 | git apply --check

Delivery control explains the full decision surface, including the blocked paths.

Where to look

Question	Command	Read more
What state is the run in?	`orcho status --verbose`	Recovery and resume
Why was it rejected?	`orcho evidence --format md`	Handoffs and advisors
What did the run actually change?	`orcho diff <run-id>`	Delivery control
Is the run state consistent?	`orcho repair-state <run-id>`	CLI reference
What verification would run?	`orcho verify list`	CLI reference

Quickstart — the happy path this page branches from.
Recovery and resume — checkpoint restore versus follow-up work.
Handoffs and advisors — every typed decision point and its actions.
Delivery control — how a retained diff reaches (or does not reach) your checkout.