Entérate cuando un worker termina o pregunta

Notificaciones de escritorio con un sonido por tipo de evento, el hook Notification propio de Claude Code, Telegram desde tu teléfono, y la escalación de ask que llega a un humano.

Objetivo#

Un worker sella, falla, se promueve, o se detiene con una pregunta — entérate sin quedarte mirando la terminal. Cuatro capas, cada una opcional y que se suman a la anterior: una notificación en esta máquina, el evento propio del CLI cuando se detiene, Telegram cuando te alejaste, y un resumen cuando vuelves.

1. En esta máquina#

notify.desktop lanza una notificación del sistema operativo en cada evento (sealed, failed, promoted, needs_approval, needs_answer, notification) — activada por defecto donde exista una pantalla:

notify:
  desktop: true # default; false apaga la notificación
  sound: on # on|off|questions (default on)

notify.sound: questions mantiene la máquina en silencio hasta que algo realmente está esperando por ti — una pregunta o una aprobación — y en silencio ante un sealed normal. Cada tipo de evento tiene su propio sonido, para que el oído distinga una tarea terminada de una pregunta sin tener que leer la pantalla.

El título de la notificación es orch · <workspace> · <seat> — el nombre del workspace y el agente/sesión que la lanzó, así varias terminales con distintos seats de Orchemax se distinguen de un vistazo. El cuerpo lleva el evento y las palabras propias de la tarea.

Comprueba que el canal funciona, o fuérzalo por una sola vez:

orch notify test --desktop --event failed

Cada emisión también queda escrita en .orch/logs/notify.log, se haya podido mostrar o no la notificación en este sistema operativo.

2. La propia detención del CLI#

Algunos eventos ocurren dentro del propio CLI del agente — necesita que respondas un permiso, o quedó inactivo esperando entrada — y nada más en Orchemax puede ver ese momento. Claude Code lo expone como un hook Notification; conectarlo es un solo comando:

orch guard wire --claude

Esto agrega una entrada Notification (alcance de proyecto, dentro del mismo bloque marcado por Orchemax que usa el resto de guard wire) que corre orch hook notification en cada prompt de permiso o espera inactiva. El hook lanza la notificación de escritorio (y Telegram, si está configurado) con el mensaje propio del CLI, deduplicado dentro de 30 segundos, y nunca bloquea al CLI — siempre sale con código 0.

El mismo comando también conecta SessionStart para correr orch notify-hook — el resumen de "al volver" del paso 5 se dispara en cuanto reabres un seat, sin esperar la primera llamada a una herramienta.

Otros CLI — cursor-agent, Copilot, opencode, agy — no tienen un evento equivalente; dependen por completo del canal de escritorio del paso 1, que se dispara al sellar sin importar qué CLI corrió la sesión.

3. Lejos de la máquina#

Vincula un bot de Telegram una vez, y cada evento que lleva el canal de escritorio también llega a tu teléfono:

Habla con @BotFather en Telegram, crea un bot, copia su token.
Pon el token en una variable de entorno y nombra esa variable en orch.yaml:
```
notify:
  telegram:
    bot_token_env: ORCH_TELEGRAM_TOKEN
```
Vincula tu chat — sin buscar el chat id a mano:
```
orch notify telegram pair
```
Esto imprime el enlace t.me del bot, espera a que envíes /start, agrega el id de tu chat a notify.telegram.chat_allowlist en orch.yaml, y envía un evento de prueba para confirmar que funcionó.

orch daemon arranca el worker de long-poll automáticamente en cuanto notify.telegram.bot_token_env está definido — nadie tiene que dejar una terminal abierta para eso. Desde un chat en la allowlist:

/status — cuántas sesiones están corriendo.
/approve <session> / /reject <session> — mezclar o descartar una sesión sellada.
/answer <id> <text> — responder la pregunta pendiente de un worker (ver abajo).

Un mensaje de cualquier chat que no esté en la allowlist recibe orch: unauthorized chat y no ejecuta nada más.

4. Preguntas#

El ask de un worker bloquea a ese worker hasta que alguien responde. Si nadie lo hace dentro de ask.escalate_after_sec (default 60 segundos — bien por debajo del timeout propio del ask, de 600 segundos), Orchemax la escala como needs_answer en cada canal configurado — escritorio, Telegram, webhooks — con la pregunta y su id de ask:

ask:
  escalate_after_sec: 60

Respóndela desde Telegram (/answer <id> <text>), o desde el CLI en esta máquina:

orch ask list
orch ask answer <id> "usa el helper compartido, no lo dupliques"

Cualquiera de los dos caminos llama al mismo AnswerAsk — el worker bloqueado se reanuda de inmediato, sin reiniciar.

5. Al volver#

Cuando abres un seat de nuevo después de estar ausente más tiempo que notify.idle_digest_min (default 10 minutos), el siguiente drain del hook — o SessionStart, que revisa sin importar el intervalo — inyecta una línea de resumen antes de los mensajes normales:

while you were away (23m): 2 sealed, 1 failed, 1 question pending (#41)

Si no hay nada que contar — ni sello, ni falla, ni pregunta pendiente — no hay línea: el resumen nunca anuncia "nothing new", ni fuerza otro turno solo para decirlo.

notify:
  idle_digest_min: 10

Lo que nunca sale de la máquina#

Cada canal de esta página lleva solo estado y resumen — nombre del evento, workspace, sesión, veredicto, el propio texto de la pregunta en needs_answer — nunca un diff ni contenido de archivo.