yasyf/orca

Orca 워커

먼저 버전에 맞는 가이드를 불러오세요: orca skills get orca-cli 및 orca skills get orchestration. 이 스킬은 워커 진입점과 소스 반환 계약을 정의합니다.

여기의 모든 orca orchestration 명령은 --full을 전달합니다: Orca 1.4.246부터 --full 없이 간결한 뷰가 출력되며, 이 경우 이 단계에서 읽는 필드가 생략됩니다. orca-worker-launch.sh와 orca-reclaim.py는 이 플러그인의 bin/ 디렉토리를 통해 PATH에 있으며, 자체적으로 --full --json을 전달합니다. 두 스크립트 모두 체크아웃 루트에서 실행하세요.

저장소 값

워커를 실행하는 저장소는 루트에 .orca.json을 체크인하며, 두 도구 모두 작업 디렉토리에서 이를 읽습니다:

{
  "ccRemote": "tools/cc-remote/bin/cc-remote",
  "ccRemoteConfig": "tools/cc-remote/config.yaml",
  "repo": "<orca-repository-id>",
  "baseBranch": "origin/main",
  "sparse": [".agents", ".claude"]
}

키	설정하는 환경 변수	경로
ccRemote	WORKER_CC_REMOTE, cc-remote CLI, 체크아웃 루트 또는 PATH 이름 기준 경로	Sprite 및 orca-reclaim.py
ccRemoteConfig	CC_REMOTE_CONFIG, cc-remote 설정, 체크아웃 루트 기준	Sprite 및 orca-reclaim.py
repo	WORKER_REPO, Orca 저장소 ID	로컬
baseBranch	WORKER_BASE_BRANCH, 로컬 워크트리가 시작되는 브랜치	로컬
sparse	WORKER_SPARSE를 설정함, 로컬 워크트리의 sparse cone	로컬

설정된 환경 변수가 해당 키보다 우선하며, WORKER_SPARSE는 파일의 cone 뒤에 디렉토리를 추가합니다. 모든 키는 선택 사항이며, .orca.json이 없는 저장소는 변수를 직접 전달합니다.

워커 실행

구현 및 테스트 워커는 기본적으로 사용되지 않는 사전 설치된 Sprite 에이전트 워크스페이스를 사용합니다. 실행기는 이를 독점적으로 확보하고, 요청된 ref를 얕게 새로 고치며, 에이전트를 준비하고, 네이티브 Task를 한 번의 호출로 연결합니다. 호환되는 사용되지 않은 워크스페이스가 준비되지 않은 경우, 레인의 워크스페이스를 새로 만듭니다. 각 할당은 설정의 orca.pool.ready를 향해 제한된 백그라운드 채우기를 시작하므로, 연속 실행은 워밍된 상태를 확보합니다. 실행이 완료된 워커는 완료 후에도 확보 상태를 유지합니다. 유지된 에이전트를 재사용하려면 명시적인 새 네이티브 Dispatch가 필요합니다.

Sprite 레인 이름은 최대 55자의 소문자, 숫자, 대시로 구성되며, 문자 또는 숫자로 시작해야 합니다:

WORKER_RUN="<소유한-run-id>" WORKER_REF=<브랜치> \
  orca-worker-launch.sh "<레인>" "<모델>" "<노력>" "<brief.md>"

이미 명명된 네이티브 Run을 소유한 터미널에서 실행하세요. 스크립트는 할당 전에 해당 바인딩을 확인하고, cc-remote orca prepare --warm을 한 번 호출한 다음, 준비된 유휴 워커를 Sprite의 Orca 서버에 하나의 네이티브 worker-start로 시작하며, 준비된 터미널과 워크트리를 재사용합니다. Prepare는 전체 brief를 VM에 복사하고 해시, 길이, 실제 체크아웃 HEAD를 기록합니다. 첫 번째 작업은 워커에게 해당 파일을 읽고 확인하도록 지시하는 포인터입니다.

Prepare는 Sprite의 Orca 런타임을 해당 orca CLI를 통해 시작하며, Orca 1.4.224는 이를 관리 서버인 orcad에서 제공합니다. 준비된 작업은 해당 서버의 빌드를 managedServer로 기록하며, 이는 준비 이벤트 orca serve --json에서 출력됩니다. 해당 필드가 없으면 스크립트는 아무것도 시작하지 않으며, 이는 Orca가 Electron으로 대체되었음을 의미합니다. Orca의 이유는 Sprite의 ~/.cc-remote/orca/serve.log에 있는 [serve] 줄에 있습니다.

실행기는 WORKER_CC_REMOTE 또는 ccRemote가 명명하는 CLI를 CC_REMOTE_CONFIG 또는 ccRemoteConfig가 명명하는 설정과 함께 실행합니다. CLI가 설정되지 않은 경우 PATH에서 cc-remote를 실행하며, 장기 실행 세션의 PATH나 최신 Homebrew 설치에 다른 릴리스가 있을 수 있으므로, 릴리스를 고정하는 저장소는 ccRemote에 자체 래퍼를 명명합니다. 설정 없이 Sprite를 실행하면 할당 전에 거부됩니다.

cc-remote는 CLI가 설정의 orca.bootstrap_helper와 정확히 일치하는 릴리스인 경우에만 Sprite를 준비합니다. 최신 패치 릴리스라도 이전 버전과 마찬가지로 실패하므로, CLI 고정과 helper는 하나의 고정 변경으로 함께 이동합니다. 할당 전에 실행기는 선택된 CLI가 출력하는 version을 설정 옆에 있는 agents-payload.json의 bootstrapHelper.version과 비교하고, 링크를 확인한 후 차이가 있으면 거부하며 둘 다 이름을 표시합니다. cc-remote는 자체적으로 동일한 확인을 수행하지만, 워밍된 확보는 spare가 확보된 후에 도달하며, 해당 spare는 실패한 상태로 유지됩니다. 설정 옆에 agents-payload.json이 없는 경우, 확인은 cc-remote에 맡겨집니다.

서명된 새 릴리스가 Mac에서 첫 실행 시 멈출 경우, 직접 복구하세요. 이는 설치 복구이며, 소유자에게 질문할 사항이 아닙니다. 선택한 실행 파일이 서명된 릴리스인지 확인하고, 해당 파일에서 com.apple.quarantine을 제거한 후 버전 명령을 다시 시도하세요:

exe="$(readlink -f "<선택한-실행파일>")"
codesign --verify --strict --check-notarization --verbose=2 \
  -R='notarized and certificate leaf[subject.OU] = "SXKCTF23Q2"' "$exe" &&
  xattr -d com.apple.quarantine "$exe"
"<선택한-cc-remote>" version

xattr는 속성이 이미 없는 경우 No such xattr를 출력합니다. -r을 전달하거나, 디렉토리를 지정하거나, Gatekeeper의 시스템 정책을 변경하지 마세요.

실행기는 --config를 전달하지 않습니다. CC_REMOTE_CONFIG를 cc-remote에 절대 경로로 내보내며, 상대 값은 호출자의 디렉토리에서 확인됩니다. 선택한 설정은 Sprite가 체크아웃할 저장소를 명명합니다. WORKER_REPO는 로컬 Orca 저장소만 선택합니다. Sprite 경로에 설정하면 시도 또는 할당 전에 거부됩니다. 실행기는 로컬 저장소 ID를 원격 저장소에 매핑하지 않습니다.

다른 바이너리/설정 쌍을 제공할 수 있습니다. 예를 들어, 체크아웃이 이동하는 동안 하나의 릴리스를 유지하는 실행기는 다음과 같습니다:

WORKER_CC_REMOTE=/절대/경로/cc-remote \
CC_REMOTE_CONFIG=/절대/경로/config.yaml \
WORKER_RUN="<소유한-run-id>" WORKER_REF=<브랜치> \
  orca-worker-launch.sh "<레인>" opus xhigh "<brief.md>"

WORKER_REF는 원격 브랜치 또는 태그를 명명하고 변경되지 않고 전달됩니다. 생략되면 설정이 ref를 제공합니다. WORKER_BASE_BRANCH는 명시적 로컬 워크트리 경로에 속합니다. 원격 브랜치로 전달하거나, 임의의 접두사를 제거하거나, 로컬 사전 조회의 커밋 ID로 요청된 ref를 대체하지 마세요. 준비된 레코드의 baseCommit은 실제 VM 베이스입니다. 원격 경로에 WORKER_BASE_BRANCH를 설정하면 거부됩니다. 로컬 경로에서는 WORKER_REF와 WORKER_EXPECT_BASE가 거부됩니다.

일반적인 브랜치 이동은 유효합니다. 작업에 정확한 베이스가 필요한 경우에만 WORKER_EXPECT_BASE를 설정하세요. 40자 또는 64자의 소문자 커밋 ID를 전체 제공하세요. 실행기는 준비 후 이를 비교합니다. 불일치 시 준비된 유휴 워커를 유지하고 worker-start 전에 중지합니다. 이 비교는 체크아웃을 선택하지 않습니다. Prepare에는 별도의 정확한 커밋 체크아웃 옵션이 없으며, 브랜치 또는 태그 이름은 철자가 16진수처럼 보여도 여전히 ref입니다.

선택한 모델과 노력을 유지하세요. WORKER_SERVICE_TIER는 명시적 Codex 서비스 티어를 변경하지 않고 전달합니다. Claude 모델과 함께 사용하면 거부됩니다. 빠른 티어는 인시던트 레인 전용입니다: WORKER_SERVICE_TIER=fast는 WORKER_INCIDENT=1이 없으면 거부됩니다. 티어가 없으면 실행기는 서비스 티어 플래그를 전달하지 않으며, codex는 표준 티어에서 실행됩니다.

WORKER_LOCAL=1은 로컬 루트(Opus 실행) 또는 루트 권한이 필요한 매우 민감한 작업(드문 Fable 할당)에 사용합니다:

WORKER_RUN="<소유한-run-id>" WORKER_LOCAL=1 \
  orca-worker-launch.sh "<레인>" opus xhigh "<brief.md>"

로컬 경로는 WORKER_REPO와 WORKER_BASE_BRANCH 또는 repo와 baseBranch에서 저장소와 기본 브랜치가 없으면 거부됩니다.

로컬 워크트리는 <레인>-<Run ID의 SHA-256 첫 8자리 16진수>로 명명되므로, 두 Run이 동일한 이름을 가지지 않습니다. 동일한 Run에서 해당 레인에 대한 두 번째 실행은 기존 활성 워크트리를 재개합니다. 이전 시도에서 만든 워크트리가 없으면 실행이 거부됩니다. 이름은 두 번 생성되지 않기 때문입니다.

새 로컬 워크트리는 sparse 다음에 WORKER_SPARSE가 명명하는 디렉토리(공백으로 구분)에 대해 sparse하며, 둘 다 비어 있으면 전체 체크아웃입니다. 실행기는 widen 명령을 출력합니다. Sparse 레인의 brief에는 "이 레인은 sparse입니다. git sparse-checkout add <dir>로 외부를 읽기 전에 확장하세요"가 포함됩니다.

설정되지 않았거나 빈 WORKER_LOCAL은 Sprite를 선택합니다. 다른 비어 있지 않은 값은 거부됩니다. 로컬 경로는 Claude만 시작하며 Codex 모델은 거부합니다. 원격 Fable은 준비 전에 거부되며, 로컬 실행이나 다른 모델로 전환되지 않습니다. 로컬 Claude는 머신의 기존 대화형 인증 및 작업 범위 우회 동작을 유지합니다. lane_env와 lane_settings 아래에서 stripped 모드로 시작되며, 자동 업데이트, 네이티브 ~/.claude 감시자, 애니메이션, 텔레메트리, 상태 표시줄이 없고, lane_denied_tools는 인간에게 멈추는 것을 방지합니다. 대화형 세션과 claude plugin update는 여전히 플러그인 캐시를 업데이트합니다. CLAUDE_LANE_SETTINGS를 JSON 객체로 설정하여 로컬 설정을 추가하세요.

작업의 허용 목록에 명명된 Model Context Protocol 서버만 시작하세요. Sprite에서 WORKER_MCP_CONFIG는 Claude용 인라인 JSON 객체 또는 Codex용 인라인 TOML 테이블을 prepare의 --mcp-config에 전달합니다. 로컬 파일 경로가 아닙니다. 로컬 경로에서 이 값은 Claude의 --mcp-config 구문을 따릅니다.

원격 Claude와 Codex는 cc-remote의 구성된 콜백에서 전용 API 키를 사용합니다. Claude는 일반 API 환경 인증을 사용합니다. 일반 도구 프로세스는 이러한 키를 상속할 수 있습니다. Codex의 경우, 고정된 CLI는 OPENAI_API_KEY, CODEX_API_KEY, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN을 기본 제공 셸 도구에서 제외합니다. 액터와 해당 네이티브 후크는 API 호출에 필요한 환경을 유지합니다. 이러한 제외는 우회 모드에서 프로세스 또는 파일 시스템 격리를 제공하지 않습니다.

API 자격 증명을 원격 액터와 허용된 하위 항목에만 유지하세요. 액터-로컬 후크 평가자는 선택한 키를 수명이 짧은 추론 하위 항목에 전달할 수 있습니다. 키를 상주 후크 데몬, 이미지, 아티팩트, 로그, 공유 파일, 전역 설정에 저장하지 마세요. API 키 변수를 전역적으로 설정하지 말고, 로컬 대화형 인증을 대체하지 말며, OAuth 새로 고침 토큰이나 전체 인증 캐시를 워커에 복사하지 마세요.

각 brief는 brief 옆에 <brief-줄기>.worker를 생성합니다. /briefs/lane-a.md의 경우 /briefs/lane-a.worker입니다. 기존 디렉토리, 링크, 실패한 시도, 레거시 <brief-줄기>.dispatch.json은 재실행을 거부합니다. 디렉토리에는 요청된 경로, 모델, 노력, 티어, ref, 선택적 예상 베이스, 로컬 brief 해시/바이트가 포함된 request.json이 기록됩니다.

원격 경로는 원시 allocation.json, prepare.err, prepare.status를 유지합니다. 요청된 레인, 실제 워크스페이스, 요청된 ref, 할당 종류, 작업 HEAD, 에이전트, brief, 환경, 터미널, <repoId>::<projectRoot> 워크트리를 검증한 후 작업을 prepared.json으로 추출합니다. 그런 다음 준비된 환경에 --on, --worktree id:<워크트리ID>, --terminal 준비된 터미널로 worker-start를 실행합니다. 두 경로 모두 worker-start.json, worker-start.err, worker-start.status를 유지합니다. 모든 결과에 대해 이러한 파일을 보관하세요.

성공하려면 worker-start 종료 코드 0과 수신 확인 메시지로 ok, 상태 ready, 소유한 Run, 출력 가능한 Task 및 Dispatch ID가 필요합니다. 실패한 수신 확인의 ID는 워커를 준비 상태로 만들지 않습니다. 성공 시 state, task, dispatch, terminal, worktree 필드가 포함된 하나의 JSON 줄을 출력합니다.

Sprite에서 JSON에는 lane, 실제 workspace, allocation(warm 또는 created)도 포함됩니다. terminal은 prepared.terminal이고 worktree는 prepared.projectRoot, 즉 VM의 체크아웃입니다. 나중에 cc-remote orca collect 호출에 해당 실제 워크스페이스를 사용하세요. 실패했거나 입증되지 않은 시작은 성공 JSON을 출력하지 않으며, 재시도나 정리 없이 시도를 유지합니다.

별도로 준비 및 연결

준비와 첫 번째 작업 연결을 별도로 검사해야 하는 경우 위에서 설명한 선택된 CLI와 설정을 사용하세요. 이 명시적인 새 Sprite 에이전트 예제는 일반 준비된 작업을 반환합니다:

"<선택한-cc-remote>" orca prepare "<레인>" --config "<설정-yaml>" \
  --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<브랜치-또는-태그>" \
  --brief-file "<전체-brief.md>" >"<새-prepared.json>"

Prepare는 선택한 에이전트를 시작하고 작업을 보내지 않고 네이티브 유휴 상태에서 중지합니다. 연결 전에 명령 종료 코드 0, prepared:true, 요청된 모델/노력, 실제 baseCommit, 정확한 brief 해시 및 길이를 확인하세요. Codex 할당의 경우 요청된 에이전트 종류, 모델, 노력, 명시적 서비스 티어를 유지하세요. API 자격 증명을 구성된 프로세스 전용 콜백에 유지하세요.

이미 Run을 소유한 코디네이터에서 준비된 레코드의 필드와 새 수신 확인 파일을 사용하여 한 번 연결하세요:

orca orchestration worker-start --run "<소유한-run-id>" --on "<환경>" \
  --worktree "id:<워크트리ID>" --terminal "<터미널>" --task-title "<레인>" \
  --spec "Lane <레인>: <brief.path>에서 전체 brief를 읽고, SHA-256이 <brief.sha256>이고 크기가 <brief.bytes>바이트인지 확인한 다음, 정확히 따르세요." \
  --full --json >"<새-수신확인.json>"

이렇게 하면 준비된 터미널과 워크트리가 재사용되고 전체 brief에 대한 포인터가 있는 네이티브 Task가 생성됩니다. 에이전트, 모델, 노력, 서비스 티어를 전달하지 마세요. 준비된 프로세스가 자체 값을 유지합니다. 준비 수신 확인은 Task와 Dispatch를 명명합니다. 기존 받은 편지함 소유자가 해당 메시지를 처리합니다. 두 번째 작업 포인터를 보내거나 다른 소비자를 시작하지 마세요. 승인된 완료 시 세션을 유지하고 소스 반환 및 수집 계약을 사용하세요. 모든 결과에 대해 수신 확인을 유지하세요. 새로 생성 실패 시 일반 CLI 롤백을 실행할 수 있습니다. 실제 남은 리소스를 보고하고 모호한 시도를 재생하지 마세요.

기록된 워크스페이스의 첫 번째 워커

버전 0.15.0은 정확히 기록된 워크스페이스와 유지된 체크아웃에 첫 번째 워커를 위한 준비 전용 --existing을 추가합니다:

"<선택한-cc-remote>" orca prepare "<기록된-워크스페이스>" --existing \
  --config "<동일-설정>" --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<브랜치-또는-태그>" \
  --brief-file "<전체-brief.md>" >"<새-prepared.json>"

또는 Sprite가 유휴 상태로 유지하는 동일한 레인/런의 워크스페이스에서:

"<선택한-cc-remote>" orca prepare "<레인>" --existing \
  --config "<동일-설정>" --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<브랜치-또는-태그>" \
  --brief-file "<전체-brief.md>" >"<새-prepared.json>"

레인/런으로 기존을 사용하는 경우 설정은 유휴 워크스페이스의 ref와 일치하는 ref를 제공해야 합니다. 준비는 워크스페이스를 확보하고, 존재하는 경우 유휴 프로세스를 재활용하며, 체크아웃과 brief를 새로 고칩니다.

orca prepare --existing은 하나의 미해결 준비만 허용합니다. 확보된 워크스페이스는 동시 준비를 거부합니다. 준비가 중단되면 워크스페이스 잠금이 해제됩니다. collect 명령은 기록된 워크스페이스 이름이 필요합니다. 이는 실행된 레인/런에서 기록됩니다. 확보된 유휴 워크스페이스가 없거나 필요한 경우 worker-start가 거부됩니다. 기존 준비는 worker-start 스크립트 흐름 외부에서 예상되므로, 독립형 orca orchestration worker-start는 --run이 필요하지 않으며 워크스페이스의 Run을 읽습니다. worker-start는 완료 시 워크스페이스를 유휴 상태로 반환하지 않습니다.

유휴 디스패치

--existing을 생략하면 준비가 새 spare를 할당합니다. 준비 없이 worker-start를 호출하면 각 워커의 failed_task_data 아래에 원시 오류가 반환됩니다.

평가 완료 대기

네이티브 Run은 일반적으로 하나의 완료 이벤트를 수신합니다. 네이티브 채팅 대화와 --resume을 지원하려면 client:tasks 런타임 이벤트를 수신하세요. 네이티브 run.wait()와 run.wait_for_done()은 하나의 완료 후 반환됩니다.

원격 워커 진단

워커 진단은 ~/.cc-remote/orca/ 아래의 항목이 포함된 orcad.log를 반환합니다. orca agent sync 메시지에 응답하지 않는 워커는 준비 중이거나 본질적으로 느립니다. 일반적으로 진단이 필요하지 않습니다. 진단이 필요할 경우 덤프하세요.

소스 반환 및 뿌리 검토 계약

실행기는 준비 레코드 아래에 allocation.json(실행기에 의해 할당된 작업 공간 ID)을 저장합니다. 작업 완료, 채팅 재개, 수동 정지 후 orca-reclaim.py가 워크트리를 호출자의 체크아웃과 동기화합니다. 작업 디스패치 partial:true 거부: 수집되지 않은 부분 디스패치는 수동 할당 취소 또는 cc-remote orca collect --retain으로 반환해야 합니다. 용어: "수집"은 결과를 반환합니다. 반환은 사용을 위해 소스를 원래 체크아웃에 다시 씁니다. 두 작업 모두 Run을 소유한 세션에서 수행됩니다.

로컬 루트 반환

로컬 워크트리는 체크아웃 아래에 있습니다. orca-reclaim.py는 request.json 옆에 reclaimed.json을 저장합니다. 워커가 작업을 완료했습니다.

Sprite 뿌리 반환

원격 워커에서 소스를 수집하려면 체크아웃 루트에서 호출하세요. 반환은 `` 안에 표시되는 준비된 워크스페이스와 할당을 읽습니다.

orca-reclaim.py "<작업-공간>" "<할당>" "<베이스-브랜치>"

선택적 --retain은 성공 후 워크스페이스 유지를 시도합니다. 유휴 유지는 권장되지 않습니다. 유지된 워크스페이스는 다음 레인에서 사용할 수 있습니다.

로컬 저장소의 baseBranch에 대한 변경 사항만 반환됩니다(없는 경우 origin/main). 이는 요청된 체크아웃 베이스와 비교되지 않습니다. 로컬 경로에는 모든 분기가 반환됩니다. 다른 분기나 워크트리 밖의 파일은 반환되지 않습니다. 반환하기 전에 모든 변경 사항이 커밋되었는지 확인하세요.

orca-reclaim.py는 빈 반환 시 경고하지 않습니다. --interactive는 각 파일마다 확인합니다. --verbose는 동기화를 자세히 표시합니다. '중단'은 병합된 파일을 표시하고 중지합니다. '스킵'은 해당 파일의 변경 사항을 삭제합니다. 병합 충돌 시 --theirs는 자동으로 원격을 선택합니다. --force-diff로 덮어씁니다. --skip-conflicts와 --abort-on-conflicts도 사용할 수 있습니다.

수집은 상태를 출력하고 반환된 각 파일에 + 접두사가 붙은 diff를 생성합니다. "collecting" 상태는 활성 수집 작업을 보여줍니다.

추가 문서

로깅 및 오류 처리에 대한 자세한 내용은 ORCA_README.md를 참조하세요. 남은 모든 문제는 작업 완료 후 협의하세요.

업데이트 로그

시스템의 이전 버전은 이전 계약을 사용했을 수 있습니다. 현재 버전은 이 문서를 따릅니다.