Unattended Orcho Runs and CI

--no-interactive is the unattended run shape. It serves two different readers with one mechanism.

If you operate runs from your own terminal, unattended means walking away: start a run, leave the desk, and come back to a typed state instead of a menu waiting for a keypress. If you run Orcho inside a CI system, unattended means a job with no human present at all. Both cases replace stdin prompts with configured answers and durable pending states.

tuned project + explicit profile + --no-interactive
  -> no stdin prompts
  -> configured defaults and policies decide routine paths
  -> eligible handoff retry may use CI advice once
  -> unsafe or ambiguous paths stop with a typed reason

Do not read this as blind automation. Read it as bounded autonomy under a declared policy.

This page assumes you already operate interactive runs. If gates, handoffs, or delivery policy are still new, read Run lifecycle, Handoffs and advisors, and Delivery control first — --no-interactive replaces exactly those prompts with configured answers.

Walking away from a run

A run takes long enough that you should not have to babysit it. The recommended walk-away posture is simple: launch with --no-interactive, leave, and read state when you return.

orcho run \
  --project ~/www/my-workspace/my-project \
  --task-file .orcho/tasks/add-login-validation.md \
  --profile feature \
  --no-interactive \
  --output summary

With the flag set, every point where an interactive run would open a menu becomes either a configured answer or a typed pending state:

• a phase handoff that needs a decision parks the run as awaiting_phase_handoff;
• a delivery or correction gate that policy cannot answer parks the run as awaiting_gate_decision with a pending delivery decision;
• unsafe or ambiguous paths stop with a typed reason instead of guessing.

Coming back is state-driven, not scrollback archaeology:

orcho status --workspace ~/www/my-workspace/workspace-orchestrator

orcho status reports one typed status from the Run state reference. Three shapes come up most often after a walk-away:

Status on return	What to do
done	Read the result: orcho evidence, orcho diff, then decide delivery if it was deferred.
awaiting_phase_handoff or awaiting_gate_decision	The run parked on a decision. orcho run --resume <run-id> presents the pending menu; decide, and the lifecycle continues.
interrupted	The process ended before a clean terminal write. Checkpoint resume continues the same run — see Recovery and resume.

One honest note about the alternative. An interactive run left unattended does not park; a prompt at a real terminal waits for input with no timeout. Nothing is lost — run state is durable and the menu is still correct when you return — but nothing progresses past that decision either. Treat interactive mode as a watching posture. If you know you might leave, launch with --no-interactive so a would-be menu becomes a resumable pending state instead of a terminal waiting for a keypress.

Running inside CI

Teams usually arrive here with an existing CI system — GitHub Actions or Jenkins with a test suite that already gates merges. Orcho runs inside such a job as a CLI step: the same --no-interactive flag, plus explicit policy, because nobody is present to answer anything.

First useful command

Use a concrete profile in CI:

orcho run \
  --project ~/www/my-workspace/my-project \
  --task-file .orcho/tasks/add-login-validation.md \
  --profile feature \
  --mode pro \
  --no-interactive \
  --output summary

For cross-project CI, make the participant set explicit:

orcho cross \
  --projects api:/repo/api web:/repo/web \
  --task-file .orcho/tasks/align-user-contract.md \
  --profile feature \
  --no-interactive \
  --output summary

On a fresh run, a non-interactive context should not rely on a terminal picker. Pass --profile explicitly. Use --profile auto-detect only when the auto-detect threshold and fallback behavior are already part of the project policy.

What the flag changes

--no-interactive removes stdin prompts from the run lifecycle.

Surface	Interactive run	Non-interactive run
Profile selection	Can show a work-kind picker.	Requires an explicit profile unless advisor policy is used.
Pre-run dirty checkout	Can ask include, exclude, commit, or halt.	Uses pre_run_dirty.non_interactive_default.
Phase handoff	Can show a handoff menu.	Persists the handoff or uses eligible CI advice under policy.
Delivery decision	Can ask apply, approve, fix, skip, or halt.	Uses delivery config or parks/blocks when policy says so.
Required verification	Human can react at the prompt.	Missing or failed required receipts block delivery.

The important point is that --no-interactive does not erase decisions. It moves them into declared policy and durable run state.

CI advice on handoffs

When a run pauses on a rejected or incomplete phase handoff, CI cannot ask the operator what to do. Orcho can run a prompt-free advice sub-flow for eligible cases:

phase rejected
  -> build handoff context
  -> ask advisor for the smallest honest retry feedback
  -> evaluate safety gates
  -> write ci_agent provenance
  -> retry through the normal handoff resume path

The current safe default is one CI advisor retry. It is intentionally narrow.

The retry can proceed only when the recommendation is retry_feedback, the confidence is not low, budget remains, the expected files stay in scope, the finding is not repeating, and no destructive marker is detected.

What CI cannot decide

Unattended execution should stop rather than hide risk.

Stop reason	Why it stops
waiver	CI must not accept known risk on behalf of the operator.
destructive action	The recommendation mentions destructive work such as hard resets or data deletion.
out of scope	The expected files do not fit the plan’s owned files or allowed modifications.
low confidence	The advisor itself is not confident enough.
repeated blocker	The same blocking finding repeats instead of improving.
budget exhausted	The bounded retry budget is spent.
release rejected	Final acceptance did not approve the delivery.
required receipts missing	Verification policy says the evidence is not strong enough.

Those stops are not failures of the concept. They are the boundary that makes unattended execution usable.

Project maturity checklist

Run unattended in CI after the project has these pieces:

Requirement	Why it matters
Explicit profile	CI should know the work shape before the run starts.
Authenticated runtimes	Worker CLI commands must run without interactive login.
Project tuning	Orcho needs project facts, paths, and verification expectations.
Required tests	Final acceptance needs receipts it can trust.
Dirty-checkout policy	CI needs a deterministic answer before worktree creation.
Delivery policy	CI needs to know whether to apply, approve, defer, skip, or block.
Accounting enabled when useful	Unwatched runs still need cost and usage visibility.

For early experimentation, run the same task interactively first. Unattended CI is strongest after the project has already taught Orcho how work should be judged.

Config surfaces

The mode is controlled by more than the CLI flag.

{
  "pre_run_dirty": {
    "non_interactive_default": "halt"
  },
  "commit": {
    "auto_in_ci": "approve"
  },
  "accounting": {
    "enabled": true
  }
}

Treat those as policy, not convenience toggles. A CI job that starts from a dirty checkout, accepts a weak release, or applies a diff without receipts is not autonomous; it is under-specified.

External CI as your verification

Orcho’s own verification proof does not come from your CI pipeline. Receipts come from the verification commands the project’s verification contract declares, executed by Orcho in the declared environment and recorded per run — read Verification receipts.

An external CI pipeline — the twenty-minute suite that already gates your merges — is a separate gate downstream of delivery. External CI results cannot be fed into Orcho as receipts. If a check must count as run evidence, declare it as a verification command so Orcho runs and records it against the run’s own tree.

Keeping both gates is the normal shape, not a workaround: Orcho’s receipts prove the run verified the right tree before delivery; your CI proves the integrated result on your own infrastructure afterward.

Delivery policy and human review

The sharpest policy decision in unattended mode is commit.auto_in_ci. Set to "approve", an unattended run that passes final acceptance and required receipts applies the diff to the project checkout and creates a commit — no human sees the change before it lands.

If your culture requires human review of every change

Do not grant unattended auto-commit. Defer the delivery decision with commit.decision_mode so the run parks a pending delivery decision for a human to decide later, or set auto_in_ci to “skip” so the diff stays in retained run artifacts until a person applies it. If auto-commit is acceptable on a working branch, keep the human gate where it already lives: the pull-request review before merge.

Whichever posture you choose, the run record stays the same: the gate verdict, the delivery decision, and who or what made it are recorded — see Delivery control.

Unattended CLI vs MCP captain

Unattended runs and MCP captain mode solve different control problems.

Mode	Best for
CLI with --no-interactive	Repeatable unattended runs in tuned projects.
MCP captain mode	A client actively observes, diagnoses, and asks the operator for decisions.

Both rely on the same principle: Orcho owns lifecycle state, decisions, and evidence. The difference is whether a human-facing client is present during the run.

Related

• Profile advisor
• Handoffs and advisors
• Delivery control
• Recovery and resume
• Run state reference
• Cost accounting
• Configuration reference
• CLI reference