yasyf/orca

Trabajadores Orca

Cargue primero las guías con versiones coincidentes: orca skills get orca-cli y orca skills get orchestration. Esta habilidad define el punto de entrada del trabajador y el contrato de retorno de fuente.

Cada comando orca orchestration aquí pasa --full: desde Orca 1.4.246 imprime una vista concisa sin él, lo que elimina los campos que estos pasos leen. orca-worker-launch.sh y orca-reclaim.py, en PATH a través del directorio bin/ de este plugin, pasan --full --json ellos mismos. Ejecute ambos desde la raíz del checkout.

Valores del repositorio

Un repositorio que lanza trabajadores incluye .orca.json en su raíz, y ambas herramientas lo leen desde el directorio de trabajo:

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

Clave	Variable de entorno que llena	Ruta
ccRemote	WORKER_CC_REMOTE, el CLI cc-remote, una ruta desde la raíz del checkout o un nombre en PATH	Sprite, y orca-reclaim.py
ccRemoteConfig	CC_REMOTE_CONFIG, la configuración de cc-remote, desde la raíz del checkout	Sprite, y orca-reclaim.py
repo	WORKER_REPO, el ID del repositorio Orca	local
baseBranch	WORKER_BASE_BRANCH, la rama desde la que comienza un worktree local	local
sparse	lleva WORKER_SPARSE, el cono sparse del worktree local	local

Una variable de entorno establecida tiene prioridad sobre su clave, y WORKER_SPARSE añade directorios después del cono del archivo. Cada clave es opcional, y un repositorio sin .orca.json pasa las variables él mismo.

Lanzar un trabajador

Los trabajadores de implementación y prueba usan por defecto un workspace de agentes Sprite preinstalado no utilizado. El lanzador lo reclama exclusivamente, refresca la ref solicitada superficialmente, prepara el agente y adjunta la Tarea nativa en una sola invocación. Cuando no hay un workspace compatible no utilizado listo, crea el workspace del carril. Cada asignación inicia un llenado de fondo finito hacia la configuración de orca.pool.ready, por lo que los lanzamientos en fila reclaman uno cálido. Los trabajadores reclamados permanecen reclamados después de la finalización; la reutilización de un agente retenido requiere un nuevo Dispatch nativo explícito.

Un nombre de carril Sprite tiene como máximo 55 letras minúsculas, dígitos y guiones, y comienza con una letra o dígito:

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

Ejecute esto desde la terminal que ya posee el Run nativo nombrado. El script verifica ese enlace antes de la asignación, llama a cc-remote orca prepare --warm una vez, luego inicia el trabajador inactivo preparado con un worker-start nativo en el servidor Orca de Sprite, reutilizando su terminal y worktree preparados. Prepare copia el brief completo a la VM y registra su hash, longitud y HEAD de checkout real. La primera tarea es un puntero que le dice al trabajador que lea y verifique ese archivo.

Prepare inicia el runtime Orca de Sprite a través de su CLI orca, y Orca 1.4.224 lo sirve en su servidor gestionado, orcad. La tarea preparada registra ese build del servidor como managedServer, leído del evento listo que orca serve --json imprime. El script no inicia nada cuando el campo falta, lo que significa que Orca recurrió a Electron. La razón de Orca es la línea [serve] en ~/.cc-remote/orca/serve.log en el Sprite.

El lanzador ejecuta el CLI que WORKER_CC_REMOTE o ccRemote nombra contra la configuración que CC_REMOTE_CONFIG o ccRemoteConfig nombra. Sin ninguno de los CLI establecidos, ejecuta cc-remote desde PATH, donde el PATH de una sesión de larga duración o una instalación más nueva de Homebrew puede contener otra versión, por lo que un repositorio que fija su versión nombra su wrapper en ccRemote. Un lanzamiento Sprite sin configuración se niega antes de la asignación.

cc-remote prepara un Sprite solo cuando el CLI es la versión exacta de la configuración de orca.bootstrap_helper; una versión de parche más nueva falla igual que una más antigua, así que el pin del CLI y el helper se mueven en un solo cambio de pin. Antes de la asignación, el lanzador compara la version que el CLI seleccionado imprime con la bootstrapHelper.version del agents-payload.json al lado de la configuración, enlaces resueltos, y rechaza una diferencia, nombrando ambas. cc-remote hace la misma comprobación él mismo, pero una reclamación cálida lo alcanza después de que el espacio libre es reclamado, y ese espacio libre entonces permanece reclamado como fallido. Una configuración sin agents-payload.json a su lado deja la comprobación a cc-remote.

Cuando una versión firmada recién instalada se detiene en su primer lanzamiento en un Mac, recupérela usted mismo. Esto es una recuperación de instalación, nunca una pregunta para el propietario. Verifique que el ejecutable seleccionado es la versión firmada, elimine com.apple.quarantine de ese único archivo, y reintente su comando de versión:

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 cuando el atributo ya no está. Nunca pase -r, nombre un directorio, o cambie la política del sistema de Gatekeeper.

El lanzador no pasa --config. Exporta CC_REMOTE_CONFIG a cc-remote como una ruta absoluta, y un valor relativo se resuelve desde el directorio de quien llama. La configuración seleccionada nombra el repositorio que el Sprite checkout. WORKER_REPO selecciona solo un repositorio Orca local; establecerlo en la ruta Sprite se niega antes de un intento o asignación. El lanzador no mapea un ID de repositorio local a un repositorio remoto.

Proporcione otro par binario/configuración, como un runner que mantiene una versión mientras su checkout se mueve, así:

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 nombra una rama remota o tag y pasa sin cambios; cuando se omite, la configuración proporciona su ref. WORKER_BASE_BRANCH pertenece a la ruta explícita del worktree local. No lo pase como la rama remota, elimine prefijos arbitrarios, o reemplace la ref solicitada con un ID de commit de una búsqueda previa local. El registro preparado baseCommit es la base real de la VM. Establecer WORKER_BASE_BRANCH en la ruta remota se niega; WORKER_REF y WORKER_EXPECT_BASE se niegan en la ruta local.

El movimiento ordinario de ramas es válido. Establezca WORKER_EXPECT_BASE solo cuando la tarea requiera una base exacta. Proporcione un ID de commit completo de 40 o 64 caracteres en minúsculas. El lanzador lo compara después de preparar; un desajuste retiene el trabajador inactivo preparado y se detiene antes de worker-start. Esta comparación no selecciona el checkout. Prepare no tiene una opción de checkout de commit exacto separada, y un nombre de rama o tag todavía es una ref cuando su ortografía parece hexadecimal.

Preserve el modelo y esfuerzo seleccionados. WORKER_SERVICE_TIER pasa un tier de servicio Codex explícito sin cambios; se niega con un modelo Claude. El tier rápido es solo para carriles de incidente: WORKER_SERVICE_TIER=fast se niega a menos que WORKER_INCIDENT=1. Sin un tier, el lanzador no pasa ninguna bandera de tier de servicio, y codex se ejecuta en el tier estándar.

Use WORKER_LOCAL=1 para una raíz local, que ejecuta Opus, o para trabajo extremadamente sensible autorizado por raíz, el único caso para Fable:

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

La ruta local se niega sin un repositorio y rama base, desde WORKER_REPO y WORKER_BASE_BRANCH o repo y baseBranch.

El worktree local se nombra <lane>-<primeros 8 hex del SHA-256 del ID del Run>, por lo que dos Runs nunca cortan un nombre. Un segundo lanzamiento para ese carril en el mismo Run reanuda su worktree en vivo; cuando el worktree que un intento anterior cortó ya no está, el lanzamiento se niega, porque un nombre nunca se corta dos veces.

Un nuevo worktree local es sparse sobre sparse seguido por los directorios que WORKER_SPARSE nombra, separados por espacios, y es un checkout completo cuando ambos están vacios. El lanzador imprime el comando de ampliación. El brief de un carril sparse lleva "este carril es sparse: amplíe con git sparse-checkout add <dir> antes de leer fuera de él".

Un WORKER_LOCAL no establecido o vacío selecciona Sprite; cualquier otro valor no vacío se niega. La ruta local inicia solo Claude y rechaza modelos Codex. Fable remoto se niega antes de preparar; nunca se convierte en un lanzamiento local o un modelo diferente. Claude local mantiene la autenticación interactiva existente de la máquina y el comportamiento de omisión con ámbito de tarea. Se inicia reducido bajo lane_env y lane_settings, sin auto-actualización, observador nativo de ~/.claude, animación, telemetría o línea de estado, y lane_denied_tools evita que se estacione en un humano. Las sesiones interactivas y claude plugin update todavía actualizan la caché de plugins. Establezca CLAUDE_LANE_SETTINGS a un objeto JSON para añadir configuraciones locales.

Inicie solo los servidores del Protocolo de Contexto de Modelo nombrados en la lista de permitidos de la tarea. En Sprite, WORKER_MCP_CONFIG pasa un objeto JSON en línea para Claude o una tabla TOML en línea para Codex a --mcp-config de prepare; no es una ruta de archivo local. En la ruta local, el valor sigue la sintaxis de --mcp-config de Claude.

Claude y Codex remotos usan claves API dedicadas de las callbacks configuradas de cc-remote. Claude usa autenticación normal de entorno API; sus procesos de herramienta ordinarios pueden heredar esas claves. Para Codex, el CLI fijado excluye OPENAI_API_KEY, CODEX_API_KEY, ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, y CLAUDE_CODE_OAUTH_TOKEN de las herramientas shell integradas. El actor y sus hooks nativos retienen el entorno necesario para las llamadas API. Estas exclusiones no proporcionan aislamiento de proceso o sistema de archivos bajo el modo de omisión.

Mantenga las credenciales API en el actor remoto y sus descendientes permitidos. Los evaluadores de hook con ámbito de actor pueden pasar claves seleccionadas a hijos de inferencia de corta duración. Mantenga las claves fuera de demonios hook residentes, imágenes, artefactos, registros, archivos compartidos y configuración global. No establezca variables de clave API globalmente, reemplace la autenticación interactiva local, o copie tokens de actualización OAuth o cachés de autenticación completas a un trabajador.

Cada brief reclama <brief-stem>.worker junto al brief. Para /briefs/lane-a.md, eso es /briefs/lane-a.worker. Un directorio existente, enlace, intento fallido, o legacy <brief-stem>.dispatch.json rechaza la repetición. El directorio registra request.json con la ruta solicitada, modelo, esfuerzo, tier, ref, base esperada opcional, y hash/bytes del brief local.

La ruta remota retiene los archivos allocation.json, prepare.err y prepare.status sin procesar. Valida el carril solicitado, workspace real, ref solicitada, tipo de asignación, HEAD de tarea, agente, brief, entorno, terminal y worktree <repoId>::<projectRoot> antes de extraer la tarea en prepared.json. Luego ejecuta worker-start con --on el entorno preparado, --worktree id:<worktreeId>, y --terminal la terminal preparada. Ambas rutas retienen worker-start.json, worker-start.err y worker-start.status. Mantenga estos archivos en cada resultado.

El éxito requiere que worker-start salga con cero y un recibo que lea ok, estado ready, el Run poseído, e IDs de Tarea y Dispatch imprimibles. Los IDs en un recibo fallido no lo hacen listo. El éxito imprime una línea JSON con los campos state, task, dispatch, terminal y worktree.

En Sprite, el JSON también nombra lane, el workspace real, y allocation (warm o created). terminal es prepared.terminal y worktree es prepared.projectRoot, el checkout en la VM. Use ese workspace real para posteriores llamadas cc-remote orca collect. Un inicio fallido o no probado no imprime JSON de éxito y retiene el intento sin reintento o limpieza.

Preparar y adjuntar por separado

Use el CLI y la configuración seleccionados descritos anteriormente cuando la preparación y el adjunto de la primera tarea necesiten inspección separada. Este ejemplo explícito de agentes Sprite frescos devuelve una tarea preparada simple:

"<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 el agente seleccionado y se detiene en inactividad nativa sin enviar su tarea. Requiera que el comando salga con cero, prepared:true, el modelo/esfuerzo solicitado, baseCommit real, y hash y longitud exactos del brief antes del adjunto. Para una asignación Codex, preserve su tipo de agente solicitado, modelo, esfuerzo y tier de servicio explícito. Mantenga las credenciales API en las callbacks de solo proceso configuradas.

Desde el coordinador que ya posee el Run, adjunte una vez con los campos del registro preparado y un nuevo archivo de recibo:

orca orchestration worker-start --run "<owned-run-id>" --on "<environment>" \
  --worktree "id:<worktreeId>" --terminal "<terminal>" --task-title "<lane>" \
  --spec "Lane <lane>: read the whole brief at <brief.path>, verify its SHA-256 is <brief.sha256> and its size is <brief.bytes> bytes, then follow it exactly." \
  --full --json >"<new-receipt.json>"

Esto reutiliza la terminal y el worktree preparados y crea la Tarea nativa con un puntero al brief completo. No pase agente, modelo, esfuerzo o tier de servicio, así que el proceso preparado mantiene los suyos propios. El recibo listo nombra la Tarea y el Dispatch. El propietario de la bandeja de entrada existente maneja sus mensajes; no envíe un segundo puntero de tarea o inicie otro consumidor. En finalización aceptada, retenga la sesión y use el contrato de retorno de fuente y recolección. Retenga los recibos en cada resultado. Un fallo de creación fresca puede ejecutar la retirada normal del CLI; reporte los recursos restantes reales y nunca reproduzca un intento ambiguo.

Primer trabajador en un workspace registrado

La versión 0.15.0 añade --existing solo para preparar para un primer trabajador en el workspace registrado exacto y checkout retenido:

"<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 "<base-ref>" \
  --brief-file "<complete-brief.md>" >"<new-prepared.json>"

Esto asume que el workspace ya está presente con el checkout en el ref solicitado, y que el agente ya está instalado. Es útil para reutilizar un workspace después de un fallo del lanzador o cuando se necesita una inspección manual entre la preparación y el adjunto de la tarea.

Retorno de fuente para revisión por raíz

Cuando un trabajador completa y la raíz necesita revisar el source, el trabajador retorna la fuente siguiendo el contrato descrito aquí. El trabajador escribe la fuente completa en el directorio designado en la VM, y el coordinador la recupera usando el mecanismo de recolección. El archivo de retorno incluye metadatos sobre el commit, el autor y la tarea realizada. El coordinador debe verificar la integridad de la fuente devuelta antes de que la raíz la revise.

Contrato de recolección

orca-reclaim.py se encarga de la recolección de workspaces después de que el trabajador ha terminado. Se ejecuta desde la raíz del checkout y lee la configuración de .orca.json para determinar qué CLI de cc-remote y configuración usar. Reclama el workspace llamando a cc-remote orca collect con el workspace real y el ID del Run.

WORKER_RUN="<completed-run-id>" \
  orca-reclaim.py "<actual-workspace>"

Esto asegura que el workspace se libera para reutilización futura. Si la recolección falla, el workspace permanece reclamado y debe ser recogido manualmente. Nunca ignore un fallo de recolección, ya que puede agotar el grupo de workspaces disponibles.

Diagnóstico remoto

Para diagnosticar un trabajador remoto que no responde, use la mensajería nativa Run para enviar un mensaje de diagnóstico al trabajador. El trabajador debe ejecutar el comando de diagnóstico y devolver el resultado. Esto es útil para verificar el estado del trabajador, inspeccionar archivos de registro, o realizar comprobaciones de conectividad.

orca orchestration worker-message --run "<owned-run-id>" --task "<task-id>" \
  --content "diagnostic" --full --json

El trabajador responderá con un mensaje que contiene los resultados del diagnóstico. Si el trabajador no responde dentro de un período de tiempo razonable, considere reiniciarlo o reemplazarlo.

Finalizar un carril

Para finalizar un carril y liberar sus recursos, envíe un comando de finalización al trabajador. Esto detiene el trabajador, reclama el workspace, y notifica al coordinador que el carril ha terminado. Use esto cuando el trabajo en el carril esté completo o cuando necesite terminar un carril prematuramente.

orca orchestration worker-stop --run "<owned-run-id>" --dispatch "<dispatch-id>" \
  --reason "completed" --full --json

Esto asegura que el trabajador se detiene limpiamente y que los recursos se liberan. Si el trabajador no responde, use la opción de fuerza después de un tiempo de espera.

Notas adicionales

• Siempre verifique que el CLI y la configuración de cc-remote coincidan en la versión.
• Nunca establezca variables de entorno de clave API globalmente; use las callbacks de cc-remote.
• Los workspaces se reclaman exclusivamente; no intente usar un workspace ya reclamado.
• Use --full --json para todas las llamadas de orquestación para asegurar la salida completa.
• Conserve los archivos de registro y estado para depuración después de fallos.