yasyf/orca

Workers Orca

Carregue primeiro os guias com versão correspondente: orca skills get orca-cli e orca skills get orchestration. Este skill define o ponto de entrada do worker e o contrato de retorno de fonte.

Cada comando orca orchestration aqui passa --full: desde o Orca 1.4.246 ele imprime uma visão concisa sem isso, o que elimina os campos que estes passos leem. orca-worker-launch.sh e orca-reclaim.py, no PATH através do bin/ deste plugin, passam --full --json por si mesmos. Execute ambos a partir da raiz do checkout.

Valores do repositório

Um repositório que inicia workers verifica .orca.json em sua raiz, e ambas as ferramentas o leem do diretório de trabalho:

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

Chave	Variável de ambiente que preenche	Rota
ccRemote	WORKER_CC_REMOTE, a CLI cc-remote, um caminho da raiz do checkout ou um nome de PATH	Sprite, e orca-reclaim.py
ccRemoteConfig	CC_REMOTE_CONFIG, a configuração cc-remote, a partir da raiz do checkout	Sprite, e orca-reclaim.py
repo	WORKER_REPO, o ID do repositório Orca	local
baseBranch	WORKER_BASE_BRANCH, o branch a partir do qual uma worktree local começa	local
sparse	leva a WORKER_SPARSE, o cone esparso da worktree local	local

Uma variável de ambiente definida prevalece sobre sua chave, e WORKER_SPARSE adiciona diretórios após o cone do arquivo. Cada chave é opcional, e um repositório sem .orca.json passa as variáveis ele mesmo.

Iniciar um worker

Workers de implementação e teste usam por padrão um workspace de agentes Sprite pré-instalado não utilizado. O lançador o reivindica exclusivamente, atualiza o ref solicitado superficialmente, prepara o agente e anexa a Task nativa em uma única invocação. Quando nenhum workspace não utilizado compatível está pronto, ele cria o workspace da lane. Cada alocação inicia um preenchimento de fundo finito em direção à configuração orca.pool.ready, então lançamentos em sequência reivindicam workspaces aquecidos. Workers reivindicados permanecem reivindicados após a conclusão; a reutilização de um agente retido requer um novo Dispatch nativo explícito.

Um nome de lane Sprite tem no máximo 55 letras minúsculas, dígitos e traços, e começa com uma letra ou dígito:

WORKER_RUN="<owned-run-id>" WORKER_REF=<branch> \
  orca-worker-launch.sh "<lane>" "<model>" "<effort>" "<brief.md>"

Execute isso a partir do terminal que já possui o Run nativo nomeado. O script verifica essa vinculação antes da alocação, chama cc-remote orca prepare --warm uma vez, então inicia o worker ocioso preparado com um worker-start nativo no servidor Orca do Sprite, reutilizando seu terminal e worktree preparados. Prepare copia o brief completo para a VM e registra seu hash, tamanho e o HEAD de checkout real. A primeira tarefa é um ponteiro informando ao worker para ler e verificar esse arquivo.

Prepare inicia o runtime Orca do Sprite através de sua CLI orca, e o Orca 1.4.224 o serve em seu servidor gerenciado, orcad. A tarefa preparada registra essa compilação do servidor como managedServer, lida do evento orca serve --json que imprime. O script não inicia nada quando o campo está ausente, o que significa que o Orca recorreu ao Electron. A razão do Orca é a linha [serve] em ~/.cc-remote/orca/serve.log no Sprite.

O lançador executa a CLI que WORKER_CC_REMOTE ou ccRemote nomeia contra a configuração que CC_REMOTE_CONFIG ou ccRemoteConfig nomeia. Com nenhuma CLI definida, ele executa cc-remote do PATH, onde o PATH de uma sessão de longa duração ou uma instalação mais recente do Homebrew pode conter outra versão, então um repositório que fixa sua versão nomeia seu wrapper em ccRemote. Um lançamento Sprite sem configuração recusa antes da alocação.

cc-remote prepara um Sprite apenas quando a CLI é a versão exata do orca.bootstrap_helper da configuração; uma versão de patch mais recente falha como uma antiga, então o pin da CLI e o helper se movem em uma única mudança de pin. Antes da alocação, o lançador compara a version que a CLI selecionada imprime com o bootstrapHelper.version do agents-payload.json ao lado da configuração, links resolvidos, e recusa uma diferença, nomeando ambos. cc-remote faz a mesma verificação por conta própria, mas uma reivindicação aquecida a alcança após o space ser reivindicado, e esse espaço então permanece reivindicado como falho. Uma configuração sem agents-payload.json ao lado dela deixa a verificação para cc-remote.

Quando uma versão assinada recém-instalada trava em seu primeiro lançamento em um Mac, recupere-a você mesmo. Esta é uma recuperação de instalação, nunca uma pergunta para o proprietário. Verifique se o executável selecionado é a versão assinada, remova com.apple.quarantine desse único arquivo e repita seu comando de versão:

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

xattr imprime No such xattr quando o atributo já se foi. Nunca passe -r, nomeie um diretório ou altere a política de sistema do Gatekeeper.

O lançador não passa --config. Ele exporta CC_REMOTE_CONFIG para cc-remote como um caminho absoluto, e um valor relativo é resolvido a partir do diretório do chamador. A configuração selecionada nomeia o repositório que o Sprite verifica. WORKER_REPO seleciona apenas um repositório Orca local; defini-lo na rota Sprite recusa antes de uma tentativa ou alocação. O lançador não mapeia um ID de repositório local para um repositório remoto.

Forneça outro par binário/configuração, como um runner que mantém uma versão enquanto seu checkout se move, como este:

WORKER_CC_REMOTE=/absolute/path/to/cc-remote \
CC_REMOTE_CONFIG=/absolute/path/to/config.yaml \
WORKER_RUN="<owned-run-id>" WORKER_REF=<branch> \
  orca-worker-launch.sh "<lane>" opus xhigh "<brief.md>"

WORKER_REF nomeia um branch remoto ou tag e passa inalterado; quando omitido, a configuração fornece seu ref. WORKER_BASE_BRANCH pertence à rota de worktree local explícita. Não o passe como o branch remoto, remova prefixos arbitrários ou substitua o ref solicitado por um ID de commit de uma pré-consulta local. O baseCommit do registro preparado é a base real da VM. Definir WORKER_BASE_BRANCH na rota remota recusa; WORKER_REF e WORKER_EXPECT_BASE recusam na rota local.

Movimentos ordinários de branch são válidos. Defina WORKER_EXPECT_BASE apenas quando a tarefa exigir uma base exata. Forneça um ID de commit completo de 40 ou 64 caracteres em minúsculas. O lançador o compara após a preparação; uma discordância retém o worker ocioso preparado e para antes do worker-start. Esta comparação não seleciona o checkout. Prepare não tem uma opção separada de checkout com commit exato, e um nome de branch ou tag ainda é um ref quando sua grafia parece hexadecimal.

Preserve o modelo e esforço selecionados. WORKER_SERVICE_TIER passa um nível de serviço explícito do Codex inalterado; ele recusa com um modelo Claude. O nível rápido é apenas para lanes de incidente: WORKER_SERVICE_TIER=fast recusa a menos que WORKER_INCIDENT=1. Sem um nível, o lançador não passa nenhuma flag de nível de serviço, e o codex executa no nível padrão.

Use WORKER_LOCAL=1 para uma raiz local, que executa Opus, ou para trabalho extremamente sensível autorizado pela raiz, o único caso para Fable:

WORKER_RUN="<owned-run-id>" WORKER_LOCAL=1 \
  orca-worker-launch.sh "<lane>" opus xhigh "<brief.md>"

A rota local recusa sem um repositório e branch base, de WORKER_REPO e WORKER_BASE_BRANCH ou repo e baseBranch.

A worktree local é nomeada <lane>-<primeiros 8 hex do SHA-256 do ID do Run>, então dois Runs nunca cortam um nome. Um segundo lançamento para essa lane no mesmo Run retoma sua worktree ativa; quando a worktree que uma tentativa anterior cortou se foi, o lançamento recusa, porque um nome nunca é cortado duas vezes.

Uma nova worktree local é esparsa sobre sparse seguido pelos diretórios que WORKER_SPARSE nomeia, separados por espaço, e é um checkout completo quando ambos estão vazios. O lançador imprime o comando de alargamento. O brief de uma lane esparsa carrega "esta lane é esparsa: alargue com git sparse-checkout add <dir> antes de ler fora dela".

Um WORKER_LOCAL não definido ou vazio seleciona Sprite; qualquer outro valor não vazio recusa. A rota local inicia apenas Claude e recusa modelos Codex. Fable remoto recusa antes da preparação; ele nunca se transforma em um lançamento local ou um modelo diferente. Claude local mantém a autenticação interativa existente da máquina e o comportamento de bypass com escopo de tarefa. Ele é iniciado simplificado sob lane_env e lane_settings, sem auto-atualização, observador nativo ~/.claude, animação, telemetria ou linha de status, e lane_denied_tools o impede de estacionar em um humano. Sessões interativas e claude plugin update ainda atualizam o cache de plugins. Defina CLAUDE_LANE_SETTINGS como um objeto JSON para adicionar configurações locais.

Inicie apenas os servidores do Model Context Protocol nomeados na lista de permissões da tarefa. No Sprite, WORKER_MCP_CONFIG passa um objeto JSON inline para Claude ou uma tabela TOML inline para Codex para o --mcp-config do prepare; não é um caminho de arquivo local. Na rota local, o valor segue a sintaxe --mcp-config do Claude.

Claude e Codex remotos usam chaves de API dedicadas dos callbacks configurados do cc-remote. Claude usa autenticação de ambiente de API normal; seus processos de ferramentas comuns podem herdar essas chaves. Para Codex, a CLI fixada exclui OPENAI_API_KEY, CODEX_API_KEY, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN e CLAUDE_CODE_OAUTH_TOKEN de ferramentas shell embutidas. O ator e seus hooks nativos retêm o ambiente necessário para chamadas de API. Essas exclusões não fornecem isolamento de processo ou sistema de arquivos sob modo de bypass.

Mantenha as credenciais de API no ator remoto e seus descendentes permitidos. Avaliadores de hooks locais ao ator podem passar chaves selecionadas para filhos de inferência de curta duração. Mantenha as chaves fora de daemons de hook residentes, imagens, artefatos, logs, arquivos compartilhados e configuração global. Não defina variáveis de chave de API globalmente, substitua a autenticação interativa local ou copie tokens de atualização OAuth ou caches de autenticação inteiros para um worker.

Cada brief reivindica <brief-stem>.worker ao lado do brief. Para /briefs/lane-a.md, isso é /briefs/lane-a.worker. Um diretório existente, link, tentativa falha ou <brief-stem>.dispatch.json legado recusa reprodução. O diretório registra request.json com a rota solicitada, modelo, esforço, nível, ref, base esperada opcional e hash/bytes do brief local.

A rota remota retém o allocation.json, prepare.err e prepare.status brutos. Ela valida a lane solicitada, workspace real, ref solicitado, tipo de alocação, HEAD da tarefa, agente, brief, ambiente, terminal e worktree <repoId>::<projectRoot> antes de extrair a tarefa em prepared.json. Ela então executa worker-start com --on o ambiente preparado, --worktree id:<worktreeId> e --terminal o terminal preparado. Ambas as rotas retêm worker-start.json, worker-start.err e worker-start.status. Mantenha esses arquivos em todos os resultados.

Sucesso requer que worker-start saia com zero e um recibo lendo ok, estado ready, o Run possuído e IDs de Task e Dispatch imprimíveis. IDs em um recibo com falha não o tornam pronto. Sucesso imprime uma linha JSON com os campos state, task, dispatch, terminal e worktree.

No Sprite, o JSON também nomeia lane, o workspace real e allocation (warm ou created). terminal é prepared.terminal e worktree é prepared.projectRoot, o checkout na VM. Use esse workspace real para chamadas posteriores de cc-remote orca collect. Um início com falha ou não comprovado não imprime JSON de sucesso e retém a tentativa sem repetição ou limpeza.

Preparar e anexar separadamente

Use a CLI e configuração selecionadas descritas acima quando a preparação e o anexo da primeira tarefa precisarem de inspeção separada. Este exemplo explícito de agentes Sprite novos retorna uma tarefa preparada simples:

"<selected-cc-remote>" orca prepare "<lane>" --config "<configured-yaml>" \
  --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<branch-or-tag>" \
  --brief-file "<complete-brief.md>" >"<new-prepared.json>"

Prepare inicia o agente selecionado e para no estado ocioso nativo sem enviar sua tarefa. Exija saída zero do comando, prepared:true, o modelo/esforço solicitado, baseCommit real e hash e tamanho exatos do brief antes do anexo. Para uma atribuição Codex, preserve seu tipo de agente, modelo, esforço e nível de serviço explícito solicitados. Mantenha as credenciais de API nos callbacks somente de processo configurados.

A partir do coordenador que já possui o Run, anexe uma vez com os campos do registro preparado e um novo arquivo de recibo:

orca orchestration worker-start --run "<owned-run-id>" --on "<environment>" \
  --worktree "id:<worktreeId>" --terminal "<terminal>" --task-title "<lane>" \
  --spec "Lane <lane>: leia o brief completo em <brief.path>, verifique se seu SHA-256 é <brief.sha256> e seu tamanho é <brief.bytes> bytes, então siga-o exatamente." \
  --full --json >"<new-receipt.json>"

Isso reutiliza o terminal e worktree preparados e cria a Task nativa com um ponteiro para o brief completo. Não passe agente, modelo, esforço ou nível de serviço, para que o processo preparado mantenha os seus próprios. O recibo pronto nomeia a Task e o Dispatch. O proprietário da caixa de entrada existente lida com suas mensagens; não envie um segundo ponteiro de tarefa ou inicie outro consumidor. Na conclusão aceita, retenha a sessão e use o contrato de retorno de fonte e coleta. Retenha recibos em todos os resultados. Uma falha de criação nova pode executar o rollback normal da CLI; relate os recursos restantes reais e nunca repita uma tentativa ambígua.

Primeiro worker em um workspace registrado

A versão 0.15.0 adiciona --existing somente preparação para um primeiro worker no workspace registrado exato e checkout retido:

"<selected-cc-remote>" orca prepare "<recorded-workspace>" --existing \
  --config "<same-config>" --provider sprites --profile agents --agent claude \
  --model claude-opus-5-5 --effort xhigh --ref "<branch-or-tag>" \
  --brief-file "<complete-brief.md>" >"<new-prepared.json>"

Retenha artefatos e use a rota de coleta separada.

Retornar fonte para revisão de raiz

Workers concluídos que um proprietário aceita como fonte candidata persistem no repositório de artefatos do agente. Use orca-reclaim.py para recolher um worker para revisão de raiz. A ferramenta transfere o diretório .worker no workspace preparado e registra o commit de retorno como uma referência imutável no registro do Run.

export WORKER_CC_REMOTE=<pinned-cli-path>
export CC_REMOTE_CONFIG=<pinned-config-path>
python3 orca-reclaim.py "<lane>" "<owned-run-id>" <path/to/artifact-repo>

Encerrar uma lane

Quando uma lane está concluída ou deve ser abandonada, use o comando nativo de despacho do Orca para encerrá-la. A partir do coordenador que possui o Run:

orca orchestration dispatch-close --run "<owned-run-id>" --dispatch "<native-dispatch-id>"

Enviar mensagens para um worker ativo

Use o sistema de mensagens nativo do Run para comunicação com o worker. A partir do proprietário do Run:

orca orchestration run-message --run "<owned-run-id>" --message "<mensagem>"

Coletar artefatos de um worker concluído

Use orca-reclaim.py para coletar artefatos quando um worker termina, mesmo sem retorno de fonte. Isso preserva briefs, logs de preparação, e arquivos de início:

export WORKER_CC_REMOTE=<pinned-cli-path>
export CC_REMOTE_CONFIG=<pinned-config-path>
python3 orca-reclaim.py "<lane>" "<owned-run-id>" <path/to/artifact-repo> --no-source

Diagnóstico remoto

Quando um worker Sprite falha ao iniciar, verifique os logs no servidor Orca:

# No Sprite, leia o log do servidor
cat ~/.cc-remote/orca/serve.log | grep '\[serve\]'

O campo managedServer no registro preparado indica se o Orca está servindo corretamente. Se estiver ausente, o Orca recorreu ao Electron e o worker não pode iniciar.

Solução de problemas

Problema	Causa provável	Ação
prepare falha com erro de versão	CLI cc-remote não corresponde ao bootstrapHelper.version	Atualize o pin do cc-remote para corresponder à configuração
worker-start falha com recibo inválido	Ambiente, worktree ou terminal preparado são inválidos	Refatore e prepare novamente com --existing no workspace registrado
Lane local falha sem worktree	Worktree anterior foi removida ou o nome colidiu	Use um novo lane name ou verifique o workspace
Lançamento remoto Fable recusa antes da preparação	Fable não é suportado em rota remota	Use rota local com WORKER_LOCAL=1 e modelo Opus ou Fable