P02 — Agent Worktree Isolation

Problem

An agent can overwrite human changes, leave generated files behind, or make it unclear which process owns a checkout.

Context

Multiple active Runs or a human working alongside an agent require separate mutation surfaces. In the workspace convention, the human/driver checkout is the Git control repository root and each canonical managed repository is below repos/.

Pattern

Create an isolated Git worktree per Run. The Run owns its branch, working directory, and cleanup lifecycle.

Diagram

workspace root (driver) → repos/api (canonical / integration)
              │
      ┌───────┼────────┐
      ▼       ▼        ▼
   Run A    Run B    Run C
  worktree worktree worktree

Example

ws run coder "Update the API" --repo api --no-integrate
# equivalent provider worktree: .workspace/runtime/worktrees/<run-id>/api
ws cleanup

Trade-offs

Worktrees are lightweight and Git-native. They share the underlying repository object store and are not security sandboxes.

Failure modes

Stale worktrees accumulate, two Runs reuse a branch, or a process continues running after its worktree is removed.

Extension points

Docker, devcontainers, VMs, Nix environments, and custom sandboxes can implement stronger execution isolation.

When not to use

For a read-only analysis Run, a separate worktree may be unnecessary if no local mutation occurs.