Handoffs and advisors

A handoff is a typed decision point.

It does not mean “the agent is confused” and it does not mean “the run is broken.” It means the selected profile or gate policy reached a point where continuing automatically would hide an important operator decision.

phase result -> handoff payload -> operator decision -> resume or stop

The handoff map

Control point	When it appears	Main surface	Typical next action
Pre-run intake	Checkout already has uncommitted changes before the run starts.	CLI prompt	include, exclude, commit, or halt
Phase handoff	A phase policy pauses the run, usually after a rejected or incomplete verdict.	`awaiting_phase_handoff`	decide, then resume
LLM handoff advice	A paused handoff needs a structured recommendation.	`orcho_handoff_advice` or `orcho_review_paused_run`	inspect advice, confirm, then decide
Resume pending decision	A client tries to resume a run that still has an unresolved handoff.	`orcho_run_resume` result	decide the handoff first
Delivery gate decision	Final delivery or correction is parked after the run reaches a release state.	`orcho_delivery_gate`	decide delivery or correction
Correction follow-up	A terminal rejection needs new repair work.	`orcho_delivery_decide`, `orcho_run_start`	start a child follow-up

These are related, but not interchangeable. A phase handoff resumes the same run after a decision. A correction follow-up starts new work because the parent run reached a terminal rejection.

Phase handoff

Phase handoff is the core mechanism.

It appears as:

status = awaiting_phase_handoff
meta.phase_handoff = {
  handoff_id,
  phase,
  verdict,
  available_actions,
  findings
}

The normal MCP flow is:

orcho_run_status(run_id)
orcho_run_evidence(run_id, slice="findings")
orcho_phase_handoff_decide(run_id, handoff_id, action, feedback?)
orcho_run_resume(run_id)

The decision tool writes the decision artifact. It does not advance execution by itself. For continue, retry_feedback, and continue_with_waiver, resume the run after the decision is recorded. For halt, the run is terminal.

Phase handoff actions

Action	Meaning	Feedback required	What happens next
`continue`	Proceed despite the handoff verdict.	no	Record override, then resume.
`retry_feedback`	Give the worker or reviewer a concrete correction and run another attempt.	yes	Record feedback, then resume into the next attempt.
`continue_with_waiver`	Accept the finding as known risk and continue with a durable waiver.	yes	Record waiver text, then resume.
`halt`	Stop the run at this handoff.	no	Mark the run halted. Do not resume.

Use retry_feedback when the finding should be fixed. Use continue_with_waiver only when the operator intentionally accepts the risk. Do not use continue as a way to avoid reading the findings.

LLM advisors

An LLM advisor is not the handoff decision.

The advisor reads the paused run and recommends the smallest honest next step. It can return a recommended action, confidence, rationale, risks, suggested retry feedback, expected files, and a durable advice artifact.

orcho_handoff_advice(run_id, handoff_id?)

For MCP clients, orcho_review_paused_run is the guided workflow: read status, read findings, propose a decision, wait for operator confirmation, then call orcho_phase_handoff_decide.

For interactive and MCP-led operation, the boundary is strict:

advisor writes advice, not a decision;
advisor can prepare a ready next action, but it is not applied automatically;
operator confirmation is still required for the actual handoff decision;
the decision note should preserve advice provenance when advice was used.

CI advice path

--no-interactive changes the handoff question because there is no terminal operator to ask.

For eligible rejected or incomplete handoffs, Orcho can run a bounded CI advice path: ask the advisor for retry feedback, evaluate safety gates, write ci_agent provenance, and retry through the same handoff decision/resume path used by human feedback.

That path is intentionally narrow. It can retry the honest, low-risk case, but it stops for waiver, destructive action, out-of-scope files, low confidence, repeated blockers, or exhausted budget. A stop leaves typed state for a later operator or client decision instead of pretending the run succeeded.

Read CI autopilot for the full non-interactive operating model.

Advisor evidence

When advice exists, the evidence bundle can include handoff_advice.

That section answers:

how many advice calls happened;
which action was recommended;
which action was actually applied;
whether an applied retry resolved, repeated, stopped, or stayed unknown;
how much observe-only advisor usage was recorded.

This matters because advice should be inspectable after the run. A useful advisor is not merely one that sounded reasonable in the moment. It should leave enough evidence to ask whether it helped.

Delivery gate decision

Delivery gate decisions happen after the run reaches a release or correction state. They are not phase handoffs.

Use:

orcho_delivery_gate(run_id)
orcho_delivery_decide(run_id, action, note?)

Common actions:

Action	Meaning
`approve`	Commit the retained worktree diff into the target checkout.
`apply`	Apply the retained diff without committing it.
`fix`	Mark the run correction-ready after a rejected release verdict.
`skip`	Close the gate without changing the target checkout.
`halt`	Leave the retained worktree for manual inspection.

If the decision is fix, the next step is usually a correction follow-up, not a checkpoint resume.

Pending decision inbox

If the client lost the run id or context, use the workspace decision inbox:

orcho_workspace_pending_decisions

It lists runs paused on actionable handoffs. Use it to recover the decision context, not to guess from old terminal output.

What not to do

Do not call orcho_phase_handoff_decide twice with different payloads for the same handoff.
Do not resume a run that is still awaiting_phase_handoff.
Do not treat LLM advice as if it were already applied.
Do not hide continue_with_waiver from the operator.
Do not use delivery decisions to patch files by hand through MCP.
Do not start a correction follow-up when checkpoint resume is the correct continuation.

Recovery and resume separates checkpoint resume from follow-up work.
Correction follow-ups explains rejected final acceptance repair.
CI autopilot explains bounded non-interactive handoff retries.
LLM captain mode explains why MCP clients are useful around handoffs.
Evidence bundle explains durable proof after the run.