Solucion de problemas

Sintoma, causa y solucion para los problemas mas comunes de orch: el reaper, locks vencidos, PATH, segundo Chair, timeouts de permiso, hooks silenciosos, y usage en cero.

Busca en esta pagina por el mensaje de error que estas viendo — cada seccion es un trio autocontenido de sintoma/causa/solucion.

El reaper reclamo una sesion que creia que seguia corriendo#

  • Sintoma: locks, una tarea en ejecucion, o un worktree de una sesion desaparecieron mientras no estabas mirando.
  • Causa: el daemon limpia sesiones muertas en un reloj (daemon.reap_interval_sec, por defecto 60s). Una vez que el seat de un agente matado/caido se ve abandonado, el reaper libera lo que tenia: sus filas de shared_locks, su fila de tarea en ejecucion, y — para un checkout aislado — su worktree.
  • Solucion: es limpieza esperada, no un bug. Para apagarla del todo (no recomendado), define daemon.reap_interval_sec: 0.

Un lock de ruta compartida no se suelta, o orch lock acquire falla#

  • Sintoma: orch lock acquire <path> --holder <id> falla, o un lock vencido bloquea una verificacion de guard.
  • Causa: los locks tienen un TTL (--ttl-min, por defecto 15 minutos) — una sesion que murio antes de liberar deja el lock tomado hasta que vence.
  • Solucion: orch lock status <path> (o sin ruta, para la lista completa) muestra expires_at; una vez vencido, cualquiera puede volver a adquirirlo. orch msg stale --older-min 15 encuentra alertas no leidas y vencidas de forma mas amplia.

orch: command not found despues de instalar#

  • Sintoma: orch no se reconoce en una terminal nueva justo despues de instalar.
  • Causa: orch setup actualiza el PATH de usuario, no el PATH del proceso actual — una terminal ya abierta no ve el cambio.
  • Solucion: abre una terminal nueva. Si sigue faltando, corre orch setup --prune-path --dry-run para ver que cree orch que esta en el PATH, y luego orch setup --prune-path para reconciliar.

"project already has Chair session … — one Chair per project"#

  • Sintoma: arrancar un segundo Chair interactivo en el mismo proyecto es rechazado con ese mensaje exacto.
  • Causa: por diseno, un proyecto corre un Chair interactivo a la vez (reclamo de seat ChairOnly) — dos Chairs compitiendo por despachar workers en el mismo proyecto duplicarian trabajo.
  • Solucion: unete a la sesion Chair existente, o despacha con --force-chair si de verdad esta muerta y el reaper aun no la atrapo. Los workers nunca chocan con esto — lanzalos con orch task run.

Un worker termina con exit 126 o 124#

  • Sintoma: el .orch-agent.log de un worker despachado termina con exit 126 o 124 y sin un diff util.
  • Causa: 126 = orch detecto una denegacion de permiso/escritura en modo headless (el CLI intento pedir permiso de forma interactiva y no pudo). 124 = llego a agents.timeout_sec (tope de reloj) o agents.idle_timeout_sec (sin stdout/stderr por ese tiempo).
  • Solucion: para 126, haz que el comando headless del preset permita escrituras sin un prompt interactivo — ver configure-agents.md. Para 124, sube agents.timeout_sec/--timeout, o sube/desactiva agents.idle_timeout_sec si el agente solo es lento.

Un hook de contexto parece no hacer nada#

  • Sintoma: context.hooks.post_tool/pre_compact esta en true en orch.yaml, pero la salida de herramientas nunca se achica y BOARD.md nunca se condensa.
  • Causa: orch hook post-tool/pre-compact resuelven orch.yaml de la misma forma que cualquier comando — fuera de un workshop registrado (sin orch.yaml resoluble) el hook simplemente retorna sin hacer nada, por diseno (un hook de contexto nunca debe fallar ruidosamente y romper al agente que se supone que ayuda).
  • Solucion: confirma que orch home resuelve un workspace desde donde corre el hook, y que orch guard wire --claude (o el wire del plugin de OpenCode) de verdad lo instalo — la bandera en orch.yaml sola no lo conecta al harness.

orch usage muestra cero justo despues de una sesion#

  • Sintoma: un seat con plan (ej. Claude Code con su propio login) acaba de correr, pero orch usage no muestra tokens para el.
  • Causa: no hay API de facturacion para un login de plan — el usage de esos seats viene de escanear los archivos de transcripcion propios del harness bajo ~/.claude/projects/<slug>/*.jsonl, lo cual puede ir detras de la sesion en vivo.
  • Solucion: vuelve a correr orch usage despues de que se escriba la transcripcion — escanea transcripciones en cada invocacion, asi que una segunda corrida es suficiente.