■ Overview 개요

Team Mode provides multi-worker coordination with bounded batch execution, task lifecycle tracking, and synthesized results. The leader agent decomposes a goal into discrete worker tasks, executes them with concurrency control, and merges outputs into a unified summary.

팀 모드는 다중 워커 조정을 제공합니다. 제한된 배치 실행, 태스크 생명주기 추적, 종합 결과를 지원합니다. 리더 에이전트가 목표를 개별 워커 태스크로 분해하고, 동시성 제어로 실행한 후 출력을 통합 요약으로 병합합니다.

Supports two execution backends: native subprocesses for fast headless operation, or tmux panes for human-readable, observable worker output. Workers receive strict guardrails that prevent recursive orchestration and scope creep.

두 가지 실행 백엔드를 지원합니다: 빠른 헤드리스 동작을 위한 네이티브 서브프로세스, 또는 사람이 읽을 수 있는 관찰 가능한 워커 출력을 위한 tmux 페인. 워커는 재귀적 오케스트레이션과 범위 확장을 방지하는 엄격한 가드레일을 받습니다.

● Enabling 활성화

Team Mode is opt-in. Set the environment variable before starting pi:

팀 모드는 옵트인입니다. pi를 시작하기 전에 환경 변수를 설정하세요:

When enabled, the team tool is registered in the root session only. Inside workers, PI_TEAM_WORKER=1 is automatically set to suppress recursive orchestration — workers cannot register the team or subagent tools.

활성화되면 team 도구가 루트 세션에만 등록됩니다. 워커 내부에서는 재귀적 오케스트레이션을 억제하기 위해 PI_TEAM_WORKER=1이 자동으로 설정됩니다 — 워커는 team 또는 subagent 도구를 등록할 수 없습니다.

▶ Command Syntax 명령어 구문

The /team slash command accepts a goal and optional key-value parameters:

/team 슬래시 명령은 목표와 선택적 키-값 매개변수를 받습니다:

Parameters:

매개변수:

★ Backends 백엔드

Team Mode supports two execution backends. The auto mode prefers tmux when available and falls back to native.

팀 모드는 두 가지 실행 백엔드를 지원합니다. auto 모드는 tmux를 사용할 수 있으면 선호하고, 없으면 네이티브로 폴백합니다.

When backend=native is forced, tmux detection is skipped entirely. When backend=tmux is forced and tmux is unavailable, pane creation fails immediately.

backend=native가 강제되면 tmux 감지를 완전히 건너뜁니다. backend=tmux가 강제되었는데 tmux를 사용할 수 없으면 페인 생성이 즉시 실패합니다.

Tmux panes are created either in the current tmux window (if pi is already inside a tmux client) or in a new detached session. Pane metadata (session, window, pane ID, attach command, log paths) is stored on each task's terminal record.

tmux 페인은 현재 tmux 윈도(pi가 이미 tmux 클라이언트 내부에 있는 경우) 또는 새로운 디태치드 세션에 생성됩니다. 페인 메타데이터(세션, 윈도, 페인 ID, 연결 명령, 로그 경로)는 각 태스크의 터미널 레코드에 저장됩니다.

● Task Lifecycle 태스크 생명주기

Team Mode tracks three levels of status:

팀 모드는 세 수준의 상태를 추적합니다:

Task Statuses 태스크 상태

Tasks are created during goal decomposition, transition to pending when eligible, and execute through in_progress to a terminal state. The blocked state is reserved for dependency-based scheduling (future).

태스크는 목표 분해 중 생성되고, 실행 가능해지면 pending으로 전환되며, in_progress를 거쳐 종료 상태로 이동합니다. blocked 상태는 의존성 기반 스케줄링용으로 예약되어 있습니다(향후).

Run Statuses 실행 상태

The overall run status reflects aggregate worker progress. cancelled and interrupted are triggered by abort signals or Ctrl+C.

전체 실행 상태는 워커 진행 상황을 집계하여 반영합니다. cancelled과 interrupted는 중단 시그널이나 Ctrl+C에 의해 트리거됩니다.

Command Statuses 명령 상태

Commands (follow-up messages) use an optimistic concurrency FSM with a statusVersion counter. Terminal statuses can transition back to queued for retry. Retries are capped at 3 attempts — exceeding this marks the command blocked.

명령(후속 메시지)은 statusVersion 카운터가 있는 낙관적 동시성 FSM을 사용합니다. 종료 상태는 재시도를 위해 queued로 다시 전환할 수 있습니다. 재시도는 최대 3회로 제한되며, 초과하면 명령이 blocked로 표시됩니다.

◆ State File 상태 파일

Every team run persists its state to a durable JSON file. This enables resume, debugging, and audit of past runs.

모든 팀 실행은 상태를 내구성 있는 JSON 파일에 저장합니다. 이를 통해 재개, 디버깅, 과거 실행 감사가 가능합니다.

Schema 스키마

Storage Location 저장 위치

Tmux logs are stored alongside the state file when using the tmux backend:

tmux 백엔드 사용 시 tmux 로그가 상태 파일과 함께 저장됩니다:

Writes are atomic — the record is written to a temp file first, then renamed.

쓰기는 원자적입니다 — 레코드를 먼저 임시 파일에 쓴 후 이름을 변경합니다.

▶ Resume & Follow-up 재개 & 후속 메시지

Interrupted or incomplete runs can be resumed by referencing their runId. Two strategies handle stale tasks:

중단되거나 완료되지 않은 실행은 runId를 참조하여 재개할 수 있습니다. 두 가지 전략으로 오래된 태스크를 처리합니다:

mark-interrupted (default) mark-interrupted (기본값)

Marks stale in_progress tasks as interrupted. Stale commands are marked stale. Use this when you want to inspect what was running and decide manually.

오래된 in_progress 태스크를 interrupted로 표시합니다. 오래된 명령은 stale로 표시됩니다. 실행 중이던 작업을 검사하고 수동으로 결정하려면 이 옵션을 사용하세요.

retry-stale retry-stale

Resets stale in_progress tasks to pending for re-execution. Stale commands are retried (attempt incremented, reset to queued). Commands exceeding 3 attempts are marked blocked.

오래된 in_progress 태스크를 pending으로 재설정하여 재실행합니다. 오래된 명령은 재시도됩니다(시도 횟수 증가, queued로 재설정). 3회를 초과한 명령은 blocked로 표시됩니다.

Follow-up Messages 후속 메시지

Send targeted messages to a specific worker or task in an existing run. The command creates a durable inbox entry, re-executes the worker with the new context, and records the result.

기존 실행의 특정 워커나 태스크에 대상 메시지를 보냅니다. 명령은 내구성 있는 인박스 항목을 생성하고, 새 컨텍스트로 워커를 재실행하며, 결과를 기록합니다.

The target can be a worker identifier (worker-1) or a task identifier (task-1).

대상은 워커 식별자(worker-1) 또는 태스크 식별자(task-1)가 될 수 있습니다.

★ Worktree Integration 워크트리 통합

Git worktree isolation can be controlled via the worktree-policy parameter:

Git 워크트리 격리는 worktree-policy 매개변수로 제어할 수 있습니다:

The resolved boolean is passed to runAgent() as the worktree option.

해석된 불리언은 worktree 옵션으로 runAgent()에 전달됩니다.

● Configuration 설정

◆ Edge Cases 엣지 케이스

Abort / Ctrl+C 중단 / Ctrl+C

When the tool's AbortSignal fires, all pending and in_progress tasks are marked interrupted, registered tmux resources are cleaned up, and the run status is set to interrupted. The abort races against normal worker completion via Promise.race().

도구의 AbortSignal이 발동하면 모든 pending 및 in_progress 태스크가 interrupted로 표시되고, 등록된 tmux 리소스가 정리되며, 실행 상태가 interrupted로 설정됩니다. 중단은 Promise.race()를 통해 정상 워커 완료와 경쟁합니다.

Session Shutdown 세션 종료

Double Ctrl+C during pi interactive shutdown emits session_shutdown during runtimeHost.dispose rather than calling session.abort(). The extension registers a session_shutdown handler that calls cleanupActiveTeamTmuxResources(), ensuring all active tmux sessions and panes are cleaned up even when the abort signal path is bypassed.

pi 인터랙티브 종료 중 이중 Ctrl+C는 session.abort()를 호출하지 않고 runtimeHost.dispose 중 session_shutdown을 발생시킵니다. 익스텐션은 cleanupActiveTeamTmuxResources()를 호출하는 session_shutdown 핸들러를 등록하여, 중단 시그널 경로가 우회되어도 모든 활성 tmux 세션과 페인이 정리되도록 합니다.

Partial Pane Cleanup on Setup Failure 설정 실패 시 부분 페인 정리

If pane creation partially fails (e.g., only 2 of 4 panes are created before an error), the already-created panes are cleaned up via cleanupTeamTmuxResources() to prevent orphaned tmux sessions.

페인 생성이 부분적으로 실패하면(예: 오류 전 4개 중 2개만 생성), 고립된 tmux 세션을 방지하기 위해 이미 생성된 페인이 cleanupTeamTmuxResources()를 통해 정리됩니다.

Active Team Tmux Resource Registry 활성 팀 tmux 리소스 레지스트리

An in-memory Set<TeamTmuxCleanupRegistration> tracks all active tmux resources across concurrent team runs. Registrations are added when tmux panes are created and removed on normal completion. The registry enables cross-run cleanup during session shutdown.

메모리 내 Set<TeamTmuxCleanupRegistration>이 동시 팀 실행 전체의 모든 활성 tmux 리소스를 추적합니다. 등록은 tmux 페인 생성 시 추가되고 정상 완료 시 제거됩니다. 레지스트리는 세션 종료 중 교차 실행 정리를 가능하게 합니다.

Failed Runs Leave Tmux Alive 실패한 실행은 tmux를 유지합니다

On success, tmux resources are cleaned immediately. On failure, tmux panes/sessions are intentionally left alive for debugging. Use cleanupActiveTeamTmuxResources() or attach to the session manually to inspect.

성공 시 tmux 리소스는 즉시 정리됩니다. 실패 시 tmux 페인/세션은 디버깅을 위해 의도적으로 살려둡니다. cleanupActiveTeamTmuxResources()를 사용하거나 수동으로 세션에 연결하여 검사하세요.