Isolation and the delivery boundary

Agents should not edit the repository they are being judged against.

Orcho keeps two places apart: the canonical project repository and the run-owned checkout where agents actually work. Everything between them flows through one controlled crossing.

{project}                        {checkout}
  canonical target repo            run-owned worktree under the runspace
       |                                |
       |  seed at run start            agents edit here
       |------------------------->     verification runs here
       |                                diff is retained here
       |                                |
       |  delivery boundary             |
       <-------------------------------
          the ONLY write-back path
          guarded by hard refusals

Two places, one diff

Path	Meaning
`{project}`	The canonical target repository the run is about.
`{checkout}`	The Orcho-provided checkout that commands and workers treat as the current subject.

With per_run worktree isolation, {checkout} is a run-owned worktree created under the workspace runspace. Agents edit there, verification commands run there, and the resulting diff stays there as a retained artifact. {project} is never touched during implementation.

This is a risk decision, not a convenience. Review, repair, receipts, and delivery all point at the same retained diff. The review subject cannot drift while the run is in flight, and a misbehaving worker turn cannot leave the source repository in a half-edited state.

The delivery boundary

The retained diff moves into {project} only through the delivery boundary, after final acceptance and an explicit decision. There is no second path. An agent cannot write into the canonical repository as a side effect of implementation; the only write-back is a deliberate approve or apply.

That single crossing is where Orcho concentrates its refusals. Only the shipping actions — approve and apply — actually write the diff, so only they can be refused by a hard guard. fix, skip, and halt never touch {project} and stay available even when delivery is blocked.

Hard guards at the boundary

Each guard is re-checked freshly against durable state at decision time and surfaces as a typed blocker on the refusal:

Blocker	What it protects
`target_dirty`	The project checkout has uncommitted changes. Refusing prevents mixing the run’s diff with unrelated parallel work.
`verification_blocked`	Required verification receipts are missing or failed. The diff does not ship without its declared proof.
`delivery_scope_violation`	The diff contains changes outside the strict delivery scope, such as sibling-repo edits. Shipping is refused; the operator can skip, halt, or re-run with an expanded scope.
`patch_invalid`	The captured run patch is corrupt — `git apply --check` rejects it. Shipping it would fail or silently mis-apply.

A refusal is not a dead end. The gate stays reversible: the run keeps its diff, evidence, and final-acceptance state, and the operator resolves the blocker or chooses a non-shipping action.

Launch-layer safety inside the checkout

Worktree isolation protects {project} from the run. A second layer, the env sandbox mode, protects the operator’s machine and logs from the agent process itself. It is launch-layer process hygiene, designed against two threats: accidental damage by the run’s own agent (a mis-fired destructive command, a fork bomb, a secret echoed into a log) and prompt injection from repository content the agent reads.

When mode=env is active, five mechanisms apply to every agent process:

env allowlist       os.environ filtered before the runtime starts;
                    the manifest records the stripped count, never the names
resource limits     cpu_seconds, memory_mb, open_files, file_size_mb caps
child cleanup       the agent and its grandchildren die when Orcho dies
output masking      known secret shapes rewritten before output.log and
                    the live echo; returned stdout stays raw for parsers
capability probe    the resolved policy and platform snapshot land in
                    meta.json.sandbox for every run

The mode never silently degrades: an unrecognized sandbox value fails fast at profile-load time instead of falling back to a weaker mode.

Just as important is what this layer does not claim. It is not a defence-in-depth duplicate of the agent runtime’s own sandbox — tool-call policy, file-access approval, and command guardrails belong to the runtime CLI. Orcho does not gate network egress and ships no filesystem or container backend inside this schema; it accepts exactly off and env. The complete stack today is launch-layer hygiene plus worktree isolation plus the runtime’s own sandbox, with each layer owning rows the others do not cover.

An operator who wants a hard enforcement boundary around the whole thing adds it outside-in: the official container image wraps the entire Orcho process — engine, worker runtimes, and worktrees together — rather than appearing as another sandbox mode. That isolation-first direction (a recorded launch envelope and a launch-mode choice per runtime) is the accepted design for this boundary; the container image is the part you can run today.

When isolation is off

Some run shapes intentionally use the direct checkout: {checkout} and {project} collapse into the same path, and the run works in the target repository itself. Review-style and planning-style runs that read the current diff, or small intentional edits, fit this shape — creating a worktree to audit a diff that already lives in the checkout would be ceremony.

What that trades away is the boundary itself. There is no retained diff as a separate review subject, no seed/deliver crossing to guard, and lower protection against accidental mutation of the source checkout. The rule of thumb from the isolation policy holds: a large feature run wants a retained worktree subject; a current-diff audit may deliberately use the project checkout.

Deep reference

The canonical engineering doc lives with the code:

docs/architecture/sandbox.md