Solucion de problemas

Sintoma, causa y solucion para los problemas mas comunes de Orchemax: 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 Orchemax 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.

"Outside the Team work schedule…"#

  • Sintoma: el despacho / spawn falla con una frase clara sobre el horario Team (no el molde plan deny: capability=…).
  • Causa: Team (o Enterprise) tiene una ventana de dia habilitada y el reloj de la empresa esta fuera de esas horas, o ese dia esta en Disable. Los dias Ignored y los horarios vacios no bloquean.
  • Solucion: espera la ventana, o pide a un admin Team que ajuste horas / Ignore el dia en orchemax.com/app/schedules. Luego refresca la lease: orch server entitlements. Ver Horarios de trabajo Team.

"every route is cooling, soonest available in Ns, beyond the Ms wait cap"#

  • Síntoma: un 502 del gateway local que nombra cada proveedor como skipped: in cooldown or circuit open, y un "soonest available" más allá del tope de espera.
  • Causa: todas las rutas de la cadena están enfriando a la vez. Un cooldown de 60 s es el camino de cuota / rate-limit (HTTP 429 o 402, o un cuerpo que diga rate limit, insufficient quota, out of credits); 300 s es el de inalcanzable. Una cadena de capas gratuitas llega al primero junta, que es lo que hace una capa gratuita.
  • Qué pasó, en disco: <taller>/.orch/gateway.err trae una línea por despacho fallido — [gateway] dispatch failed model=… class=cooling err=… — y el texto del error nombra cada proveedor que intentó y por qué. orch usage muestra los intentos; una fila con error_class=cooling es esto, no una falla del proveedor.
  • Arreglo: deja que espere en vez de rendirse. gateway.cooldown_wait_ms limita esa espera (0 = el default de 30 s del router, negativo = nunca esperar); 90000 cubre un cooldown de 60 s con margen. Reinicia el gateway después de editarlo (orch gateway service restart) y la línea de arranque reporta el tope vigente. Si las capas gratuitas no alcanzan, suma una ruta paga a la cadena.

"…allows N concurrent worker…" / tope de Chairs abiertos#

  • Sintoma: el spawn se niega porque los workers concurrentes estan llenos, o abrir otro Chair interactivo choca con el techo de Chairs abiertos del plan.
  • Causa: orch.agents.concurrent mide workers; orch.agents.max mide Chairs abiertos (los Chairs solo-MCP no consumen el medidor de workers).
  • Solucion: espera a que termine un worker, cierra un Chair idle, o sube de plan. El roster opcional agents.workers en orch.yaml solo prefiere modelos baratos — no sube el tope.

Friccion de modelo / MCP en OpenClaude#

  • Sintoma: el picker siempre muestra orchemax/pareto; o mcp__orch__verify_status has been denied en modo dontAsk.
  • Causa / solucion: ver Ajustes comunes del asiento (pin de env.OPENAI_MODEL; dontAsk vs bypassPermissions + mcp__orch__*).

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 = Orchemax 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.

cursor-agent dice que un hook fallo con un syntax error cerca de &#

  • Sintoma: un worker corriendo cursor-agent en Windows tiene todas las herramientas bloqueadas, y su log muestra un hook que muere con syntax error near unexpected token '&'.
  • Causa: cursor-agent elige bash para evaluar su propio wrapper de hook (con sabor a PowerShell) cuando el proceso tiene una variable SHELL con pinta POSIX — la cual hereda cuando el Chair mismo corrio bajo Git Bash (Claude Code → orch mcp → worker). Orchemax quita SHELL/MSYSTEM* del entorno de un worker despachado justamente por esto; una version anterior de orch no lo hacia.
  • Solucion: actualiza orch. Si vuelve a pasar, confirma que nada mas vuelva a definir SHELL en el workspace o en la config del agente antes de que arranque.

Un worker cierra "ok" pero su log dice "MCP server does not exist: orch"#

  • Sintoma: el .orch-agent.log de un worker despachado muestra que el propio CLI se queja de no tener servidor MCP orch (MCP server does not exist: orch o orch MCP is not connected), pero la sesion igual cierra y verify_status antes leia guardrails: ok.
  • Causa: el CLI cargo solo su config MCP global de la maquina y nunca aprobo el .cursor/mcp.json / .mcp.json / .orch/mcp.json propio del worktree — todas las herramientas MCP del lado worker (msg_send, verify_report, lock_acquire, code_snippet, search_shared_symbols) fueron inalcanzables toda la sesion. Para cursor-agent en concreto: cursor-agent mcp list muestra el servidor del proyecto atascado en "not loaded (needs approval)" en modo headless, porque no hay nadie para aprobarlo.
  • Solucion: actualiza orch — el preset cursor ahora agrega --approve-mcps, y la verificacion ahora falla con razon orch MCP unavailable in worker cuando el log trae ese marcador, en vez de leer "ok". Si otro CLI todavia muestra esto, confirma que tenga una bandera documentada o una convencion de config de workspace para cargar servidores MCP de proyecto en modo headless (copilot lee .mcp.json por su cuenta; agy no tiene config MCP por workspace en absoluto — corre orch guard wire --agy --scope user --allow-user-scope una vez para registrar orch en su config global, que es justo lo que te dice su linea de razon — ver configure-agents.md).

orch cursor se congela en “MCP servers need to be approved”#

  • Sintoma: Cursor interactivo pide Approve del MCP orch y se queda en Applying your selection... hasta que matas la terminal.
  • Causa: la whitelist de aprobación MCP de Cursor (mcp-approvals.json) hashea la entrada del server del proyecto. Orch reescribe .cursor/mcp.json con un ORCH_SESSION nuevo cada seat → el hash no coincide y el TUI vuelve. Sin --approve-mcps en el preset interactivo ese diálogo es inevitable, y al aplicar a menudo se cuelga bajo la consola del asiento.
  • Solucion: actualiza orch (default interactivo: cursor-agent --approve-mcps --trust). O pon lo mismo en agents.interactive.cursor / ORCH_AGENT_CMD. Matriz de allowlists de otros CLIs: ajustes comunes — allowlists del vendor.

Cursor / Claude plan / Codex perdieron conectores tras gateway connect#

  • Sintoma: tras pegar :8788 / orch_gk_… en Cursor, Claude Code o Codex, el asiento pide API key, pierde conectores del plan, o el gateway responde 403 a un bearer OAuth.
  • Causa: esos asientos default a login / plan del vendor — el tráfico de modelos no pasa por el gateway. El gateway es solo para asientos API-key / BYO.
  • Solucion: restaura el login del vendor; pon agents.auth.<preset>: account (o déjalo sin setear). No apuntes asientos de plan al gateway. Ver ajustes comunes — asientos con login/plan.

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.