Worktree Isolation 워크트리 격리

● Overview 개요

ROACH PI uses temporary git worktrees to isolate subagent and team worker edits from the main checkout. Every subagent or team worker that requests worktree isolation runs inside a detached worktree — a separate working directory backed by the same repository object store.

ROACH PI는 서브에이전트와 팀 워커의 편집을 메인 체크아웃에서 격리하기 위해 임시 git 워크트리를 사용합니다. 워크트리 격리를 요청하는 모든 서브에이전트나 팀 워커는 디태치된 워크트리 — 동일한 저장소 객체 저장소를 기반으로 하는 별도의 작업 디렉토리 — 에서 실행됩니다.

After the run completes, a complete diff artifact is captured before the worktree is cleaned up. This gives you a full record of every change the agent made — files added, modified, or deleted — without any risk of polluting your working tree.

실행이 완료된 후, 워크트리가 정리되기 전에 완전한 diff 아티팩트가 캡처됩니다. 작업 트리를 오염시킬 위험 없이 에이전트가 수행한 모든 변경 — 추가, 수정 또는 삭제된 파일 — 에 대한 전체 기록을 얻을 수 있습니다.

▶ How It Works 작동 방식

The worktree lifecycle follows a strict sequence of steps:

워크트리 라이프사이클은 다음 엄격한 단계 순서를 따릅니다:

1. git rev-parse --show-toplevel — Find git root — Git 루트 찾기

   Resolve the repository root directory. All subsequent git operations use this path.

   저장소 루트 디렉토리를 확인합니다. 이후 모든 git 작업은 이 경로를 사용합니다.

2. mkdtemp(tmpdir(), pi-subagent-worktree-${runId}-) — Create temp directory — 임시 디렉토리 생성

   Allocate a unique temporary directory in the system temp folder. The runId ensures no collisions between concurrent runs.

   시스템 임시 폴더에 고유한 임시 디렉토리를 할당합니다. runId는 동시 실행 간 충돌을 방지합니다.

3. git worktree add --detach <path> HEAD — Create detached worktree — 디태치된 워크트리 생성

   Create a detached worktree at the current HEAD commit. No branch is created — the worktree starts as a clean mirror of the current repository state.

   현재 HEAD 커밋에서 디태치된 워크트리를 생성합니다. 브랜치는 생성되지 않습니다 — 워크트리는 현재 저장소 상태의 깨끗한 미러로 시작합니다.

4. Subagent/team worker cwd mapped into worktree 서브에이전트/팀 워커 cwd를 워크트리에 매핑

   The agent's working directory is translated from the main checkout path to the equivalent path inside the worktree. All file reads, writes, and command executions happen in isolation.

   에이전트의 작업 디렉토리가 메인 체크아웃 경로에서 워크트리 내부의 해당 경로로 변환됩니다. 모든 파일 읽기, 쓰기 및 명령 실행이 격리된 상태에서 이루어집니다.

5. Capture diff artifacts Diff 아티팩트 캡처

   After the agent finishes: capture git status --short, git diff --stat, git diff, and git diff --cached from the worktree.

   에이전트 완료 후: 워크트리에서 git status --short, git diff --stat, git diff, git diff --cached를 캡처합니다.

6. Write worktree.diff.md to artifact directory 아티팩트 디렉토리에 worktree.diff.md 작성

   All captured output is written to <artifactDir>/worktree.diff.md in a structured markdown format.

   캡처된 모든 출력이 구조화된 마크다운 형식으로 <artifactDir>/worktree.diff.md에 작성됩니다.

7. git worktree remove --force <path> — Cleanup worktree — 워크트리 정리

   Remove the temporary worktree. The --force flag handles uncommitted changes and locked files. The temp directory is then deleted.

   임시 워크트리를 제거합니다. --force 플래그는 커밋되지 않은 변경과 잠긴 파일을 처리합니다. 그 후 임시 디렉토리가 삭제됩니다.

■ Diff Capture Format Diff 캡처 형식

The diff artifact is written as a structured markdown file. This is the exact format produced at <artifactDir>/worktree.diff.md:

Diff 아티팩트는 구조화된 마크다운 파일로 작성됩니다. <artifactDir>/worktree.diff.md에 생성되는 정확한 형식입니다:

● Cleanup States 정리 상태

The worktree cleanup process tracks its outcome as one of four states:

워크트리 정리 프로세스는 결과를 다음 네 가지 상태 중 하나로 추적합니다:

★ Using with Subagents 서브에이전트와 함께 사용

Enable worktree isolation for individual subagent calls by setting worktree: true in the subagent tool options:

서브에이전트 도구 옵션에 worktree: true를 설정하여 개별 서브에이전트 호출에 대해 워크트리 격리를 활성화합니다:

The subagent runs entirely inside the worktree. All file edits, new files, and deletions are isolated. When the subagent finishes, the diff is automatically captured to the specified artifactDir.

서브에이전트는 워크트리 내부에서 완전히 실행됩니다. 모든 파일 편집, 새 파일 및 삭제가 격리됩니다. 서브에이전트가 완료되면 diff가 지정된 artifactDir에 자동으로 캡처됩니다.

◆ Using with Team Mode 팀 모드와 함께 사용

In team mode, set the worktree policy via the /team command:

팀 모드에서는 /team 명령을 통해 워크트리 정책을 설정합니다:

Each team worker gets its own isolated worktree. Diffs are captured to per-worker artifact directories, so you can review each worker's changes independently.

각 팀 워커는 자체 격리된 워크트리를 갖습니다. Diff가 워커별 아티팩트 디렉토리에 캡처되므로 각 워커의 변경을 독립적으로 검토할 수 있습니다.

● Edge Cases 엣지 케이스

Worktree Creation Failure 워크트리 생성 실패

If git worktree add fails (e.g. the repository is in a state that doesn't support worktrees, or the temp directory is unavailable), the system falls back to no isolation. The agent runs in the main checkout as usual. This is logged but does not fail the run.

git worktree add가 실패하면(예: 저장소가 워크트리를 지원하지 않는 상태이거나 임시 디렉토리를 사용할 수 없음), 시스템은 격리 없이 폴백합니다. 에이전트가 평소처럼 메인 체크아웃에서 실행됩니다. 이는 로그에 기록되지만 실행을 실패시키지 않습니다.

Diff Buffer Overflow Diff 버퍼 오버플로우

The combined diff output is capped at 1,048,576 bytes (1 MB). If the agent generates a diff larger than this, the output is truncated at the buffer boundary. The artifact header always records the max buffer size so consumers can detect potential truncation.

결합된 diff 출력은 1,048,576 바이트(1 MB)로 제한됩니다. 에이전트가 이보다 큰 diff를 생성하면 출력이 버퍼 경계에서 잘립니다. 아티팩트 헤더에 항상 최대 버퍼 크기가 기록되어 소비자가 잠재적 잘림을 감지할 수 있습니다.

Cleanup Failure 정리 실패

If git worktree remove --force fails (e.g. a process still holds a file handle in the worktree), the cleanup state is set to failed. The failure is logged but does not fail the run. The temp directory may remain on disk and will be cleaned up by the OS temp directory reaper.

git worktree remove --force가 실패하면(예: 프로세스가 여전히 워크트리의 파일 핸들을 보유 중), 정리 상태가 failed로 설정됩니다. 실패는 로그에 기록되지만 실행을 실패시키지 않습니다. 임시 디렉토리가 디스크에 남을 수 있으며 OS 임시 디렉토리 정리기에 의해 정리됩니다.

Concurrent Worktrees 동시 워크트리

Each run uses a unique temp directory suffixed with the runId, so concurrent subagents or team workers never conflict. Git itself supports multiple worktrees on the same repository natively.

각 실행은 runId가 접미사로 붙은 고유한 임시 디렉토리를 사용하므로 동시 서브에이전트나 팀 워커가 충돌하지 않습니다. Git 자체가 동일한 저장소에서 여러 워크트리를 기본적으로 지원합니다.