Delivery Control for Orcho Runs

Delivery control is the last part of the run lifecycle.

The worker may have produced a diff. Review may have no findings. Final acceptance may still reject delivery because required receipts are missing, the target checkout is not clean, or the operator must make a decision. Orcho keeps those states separate instead of treating “there is a diff” as “the work is ready.”

Delivery journey

Think of delivery as a controlled journey from run-owned work to the project checkout:

retained run final gate operator decision target checkout recorded outcome

The important point is not that Orcho can apply a patch. The important point is that every delivery decision has an explicit status, a bounded set of allowed actions, and a recorded outcome.

Here is that journey end-to-end in a real run — the isolated diff, the approving gate, the operator’s bounded decision, the clean-checkout re-check, and the structured ship: a DCO-signed commit on an orcho/deliver/… branch with a pull request, never a silent commit on main (press play, or scroll it into view):

delivery · a real run · from a held diff to a reviewable PR

retained run
final gate
operator decision
target checkout
structured delivery

isolated the run produced a diff — held in run artifacts, not yet in your checkout

isolation is on: the worker never wrote to the project checkout. source_worktree ≠ project_dir
final_acceptance APPROVED ship_ready = yes

a REJECTED gate here would not trap you — the override stays visible in the run record.
gate verdict ≠ operator decision — a bounded, recorded action set:
- fix keep run, correction follow-up
- approve override + commit
- apply diff in checkout, uncommitted
- skip retain, do not deliver
- halt stop, mark halted
target checkout clean — safe to write

if the checkout went dirty from parallel work, delivery pauses for retry — it never blind-applies over someone else's changes.
structured delivery — not a silent commit on main
1. rebase onto a fresh origin/main
2. commit DCO-signed git commit -s
3. branch orcho/deliver/20260704_111547-…
4. publish git-provider plugin pushes + opens a pull request
✓ PR opened orcho-core #24 a reviewable unit over a signed commit — core stays provider-neutral

A real run's delivery journey. The isolated run holds a diff; final acceptance approves; the operator picks approve from a bounded action set; the target checkout is re-checked clean; and delivery ships a DCO-signed commit on an orcho/deliver/… branch with a pull request — never a silent commit on main. Agents speak JSON to Orcho; Orcho speaks structured delivery to humans. Behavior from ADR 0119/0121; publishing is a provider-neutral plugin seam.

Happy paths

There are two normal delivery shapes.

Path	Meaning
Final acceptance approves	The run is ship-ready according to the configured gates. Delivery can apply or commit the diff according to the selected command and policy.
Operator applies without commit	The operator wants the diff in the project checkout but wants to inspect, amend, or commit manually. The run still records how the diff left the retained run.

In both paths, Orcho should make the handoff visible: what diff is being delivered, where it came from, which receipts exist, and what was written into the target checkout.

Rejected gate path

Final acceptance can reject even when the code diff looks reasonable. That is a feature, not a contradiction. A rejected gate means the release evidence is not strong enough for the selected profile.

Final acceptance
  verdict     REJECTED
  ship_ready  no
  summary     code changes match the contract, but required receipts are missing

Correction gate -- acceptance rejected
  Final acceptance did NOT approve this change.
  Default is fix: keep the worktree and run a correction follow-up.

  What do you want to do?

    1) fix      Continue with a correction follow-up.
    2) approve  Override final acceptance, apply the diff, and commit.
    3) apply    Override final acceptance and leave the diff uncommitted.
    4) skip     Retain artifacts and do not deliver.
    5) halt     Do not deliver and mark the run halted.

This menu is a delivery control surface. It is not just a prompt. The operator is deciding whether to preserve the gate result, override it knowingly, park the diff, or stop the run as a blocked delivery.

Operator override harness

This is the important harness use case: delivery is blocked, but the operator is not trapped.

Final acceptance may say REJECTED because evidence is incomplete. That is the system doing its job. The operator can still decide that the diff should move forward because they have outside context, accept the risk, or want the change in the project checkout for manual completion.

Blocked does not mean powerless

Orcho separates the gate verdict from the operator decision. A rejected delivery can be fixed, overridden with a commit, applied without a commit, parked, or halted. The important part is that the override remains visible in the run record.

Here is that override in a real dogfood run — and the reason matters: final acceptance rejected on receipts, not code. The change was contract-correct and every runnable check passed, but the mandated .venv/bin/… receipts could not be captured in the isolated checkout. The operator held outside context and picked apply: the diff lands in the project checkout uncommitted — no branch, no commit, no pull request — for manual finish (press play, or scroll it into view):

delivery · override path · blocked ≠ powerless

review_changes APPROVED round 1 · handoff bypassed

the code review passed — SDK-only feed, the picker stays a dumb renderer, bare CLI opens the picker, selection uses the pinned locator.
final_acceptance REJECTED receipts, not code

the M5 code path is consistent with the contract and focused/full checks pass under the available Python — but the required .venv/bin/… receipts are unconfirmed: there is no .venv in the isolated checkout. The gate won't call it ship-ready if it can't prove it in the mandated environment.
- task_contract satisfied
- interfaces compatible
- tests weak
the operator is not trapped — a bounded, recorded action set:
- 1 🔧 fix correction follow-up, same worktree
- 2 ✅ approve override + commit
- 3 📥 apply override, apply uncommitted
- 4 ⏭ skip retain, do not deliver
- 5 🛑 halt mark the run halted
operator picks 3 · apply — outside context says the code is fine; receipts will be captured by hand
📥 applied to project checkout — no commit applied_uncommitted

no branch, no commit, no pull request — the diff lands as working-tree changes on main for manual finish:

modified M src/orcho_tui/app.pyM src/orcho_tui/cli.pyM src/orcho_tui/feeds/__init__.pyM src/orcho_tui/screens/__init__.pyM tests/unit/test_import_boundaries.py

untracked ?? src/orcho_tui/feeds/workspace.py?? src/orcho_tui/screens/picker.py?? tests/pilot/test_picker.py?? tests/unit/test_workspace_feed.py

the operator will commit manually — and the override stays visible in the run record.
delivery blocked — the pipeline ran, delivery was an explicit, recorded decision

plan ✓validate_plan ✓implement ✓review_changes ✓repair_changes ⏭final_acceptance ✗

artifacts and the worktree are retained. Not a silent commit, not a lost diff — a blocked release the operator resolves on their own terms.

The override half of delivery, from a real dogfood run. Final acceptance rejected on receipts, not code — the mandated .venv/bin/… checks had no receipt in the isolated checkout. The operator overrode with apply: the diff is written to the project checkout uncommitted, with no branch and no pull request, for manual finish. Orcho keeps the gate verdict and the operator's decision as separate, recorded facts — the companion to the happy ship path. Behavior verified against commit_delivery.py (applied_uncommitted).

Decision	Use when	Result
`fix`	The gate is right and the run needs more work.	Keep the retained run and start a correction follow-up.
`approve`	The operator accepts the risk and wants a committed delivery.	Apply the diff to the project checkout and create a commit.
`apply`	The operator wants the diff locally but not committed yet.	Apply the diff and leave the checkout dirty for manual work.
`skip`	The diff should be preserved but not delivered now.	Keep artifacts and finish without moving the diff.
`halt`	The run should be marked blocked or wrong.	Stop delivery and record the halted outcome.

That flexibility matters because AI delivery is not a binary machine decision. Sometimes the system should block. Sometimes the operator should override. Orcho’s job is to make both states explicit.

Dirty target checkout during delivery

The pre-run dirty checkout question protects the beginning of a run. Delivery has a second, different dirty-checkout problem: the project checkout can become dirty while the isolated run is still working.

Orcho should not blindly apply a retained run diff on top of unrelated parallel work. If the target checkout changed during the run, delivery pauses before writing into it.

Delivery paused -- project checkout is dirty
  Delivery is paused to avoid mixing this run with parallel work.

  Uncommitted changes in target checkout:
    M src/final_screen.py

  What do you want to do?

    1) retry  Re-check the project checkout after you clean it up.
    2) skip   Do not deliver; keep the diff in retained run artifacts.
    3) halt   Do not deliver and mark the run halted.

Choose [retry]: retry
Committed to project checkout ...

retry is the important action in this case. It lets the operator clean, stash, commit, or otherwise resolve the target checkout, then ask Orcho to re-check and continue the same delivery decision. The run does not lose its diff, evidence, or final acceptance state.

Why this belongs inside run control

Dirty checkout handling is not a headline feature. It is one part of the delivery control contract.

The broader value is that Orcho distinguishes:

a run that produced changes;
a run that passed or failed final acceptance;
a run whose diff is retained but not delivered;
a run whose delivery was blocked but intentionally overridden;
a run that cannot deliver because the target checkout changed;
a run that can retry delivery after the operator resolves the checkout.

That distinction keeps agent work from turning into an uncontrolled pile of diffs, logs, partial receipts, and vague “looks done” claims.