xonecode 0.38.44 → 0.39.4

package/dist/web/servidor/corredorDeTareas.d.ts

@@ -0,0 +1,395 @@
+/**
+ * El corredor: coge tareas de la cola, las corre y escribe sus transiciones.
+ *
+ * **Un solo corredor por máquina**, con cerrojo de pid: dos consolas abiertas serían dos
+ * ejecutores sobre la misma cola, y con ellos dos turnos del mismo proyecto a la vez. El
+ * segundo proceso sirve el dashboard y NO ejecuta, y lo dice (`corriendoAqui()`): un kanban
+ * que se ve igual en dos ventanas pero solo avanza en una tiene que decir en cuál.
+ *
+ * **Y el cerrojo solo no basta.** Su recogida cuando el dueño parece muerto no se puede
+ * hacer atómica con primitivas de sistema de ficheros —«está muerto» es la observación de
+ * un instante— y deja un residuo declarado en `agent/tareas/tareasEnDisco.ts#recoger` en el que
+ * dos procesos pueden creerse dueños. Lo que hace verdad «un solo corredor» son las DOS
+ * comprobaciones de aquí, y hacen falta las dos:
+ *  - `sigoSiendoDueño()` **antes de despachar cada tarea**, no solo al arrancar: es lo que
+ *    hace que el que perdió el cerrojo se entere ANTES de abrir una consola.
+ *  - y la ESCRITURA final condicionada a que la tarea siga siendo la nuestra (ver
+ *    `escribirSiSigueSiendoNuestra`): la comprobación del despacho no cubre el momento de
+ *    escribir el resultado, que llega minutos después.
+ *
+ * La política de QUÉ arranca no está aquí: es `core/tareas.ts#siguientesAEjecutar`, pura y
+ * con sus tests. Aquí está el lazo, que es lo que no se puede probar sin dobles.
+ */
+import { type Tarea } from "../../core/tareas.js";
+import { type ResultadoDeTurno } from "../../core/entrega.js";
+import type { JuezDeTareaPort } from "../../core/ports.js";
+import type { PantallaElegida } from "../../core/tareas.js";
+import type { ConsolaDeProyecto } from "./vestibulo.js";
+import type { Sumidero } from "./transporte.js";
+import type { Acto } from "../../core/actos.js";
+import type { TareasEnDisco } from "../../agent/tareas/tareasEnDisco.js";
+/**
+ * Lo que git sabe de una sesión, y que la puerta de la entrega necesita entero.
+ *
+ * Las dos cosas salen de UNA pregunta (`cambiosDeSesion`): si hay «antes» con que comparar,
+ * y si la sesión cambió algo. `escribio` solo se puede afirmar con marca — sin ella no es
+ * que no escribiera, es que no hay con qué mirarlo (ver `MedidaDeEntrega.escribio`).
+ */
+export interface RevisionDeSesion {
+    revisable: boolean;
+    escribio?: boolean;
+    /** QUÉ cambió, con la ruta RELATIVA que da git. Sale de la MISMA medida que `escribio`
+     *  —una sola llamada, las dos derivadas en la misma expresión, así que no pueden
+     *  discrepar—, y de aquí sale el hecho que se le cuenta al juez. Ausente cuando no hay
+     *  marca; `[]` cuando git dice que no cambió nada. */
+    cambiados?: readonly string[];
+}
+/**
+ * La `revisable` de PRODUCCIÓN, sobre `cambiosDeSesion`.
+ *
+ * Vive aquí y no en un cierre de `arrancarConsolaWeb` por la razón de siempre en este repo:
+ * ahí dentro no se puede llamar, y todos los tests de esa función doblan lo que la rodea —
+ * así que esta derivación podía quedarse mal con todo en verde. Medido: una mutación que
+ * hacía `escribio: true` a fuego sobrevivió a las 25 mutaciones de la tanda anterior.
+ *
+ * **`revisable` es «alguien puede mirar esto», y eso vale con las DOS medidas**: la
+ * atribución por commit (`via: "git"`) y el respaldo contra la foto de apertura
+ * (`desde-apertura`, el único posible en un proyecto donde no se commitea — offline, o la
+ * carpeta que abrió una persona). Exigir solo la primera habría dejado sin entregar TODA
+ * tarea de un proyecto fuera del workspace, que es donde `commitearTurno` no commitea a
+ * propósito. `sin-marca` sigue siendo la única que no se puede revisar.
+ *
+ * **Lo que sí distingue las dos es `cambiados`**: se quitan los ficheros que nadie ha
+ * commiteado, porque no consta de quién son. Para una tarea eso no esconde nada suyo —
+ * `commitDeTurno` corre en el `finally` del turno y se ESPERA, así que cuando la puerta de
+ * entrega pregunta, lo que la tarea escribió ya está commiteado— y en cambio evita
+ * atribuirle lo que estuviera suelto de antes. En el respaldo no hay ninguna fila marcada,
+ * así que ahí la lista es exactamente la de siempre: todo lo que cambió desde la apertura,
+ * de quien sea.
+ *
+ * Las tres respuestas posibles, y la del medio es la que sostiene todo:
+ *  - con ficheros → hay «antes» con que comparar y la sesión cambió algo.
+ *  - sin ficheros → hay «antes» y la sesión NO cambió nada. Es lo único que permite
+ *    entregar una tarea de solo lectura, y viene de git y nunca de `autorizadas`, que es la
+ *    intención del agente y no el hecho.
+ *  - `sin-marca` → no hay con qué mirarlo, así que **no se afirma nada** sobre si escribió:
+ *    el campo se queda ausente y la condición del verificador se exige como siempre.
+ */
+export declare function revisionConGit(cambiosDeSesion: (raiz: string, sesion: string) => Promise<{
+    via: string;
+    ficheros: readonly {
+        ruta: string;
+        sinCommitear?: true;
+    }[];
+}>): (raiz: string, sesion: string) => Promise<RevisionDeSesion>;
+/**
+ * Lo que le pasa a una tarea cuya consola se cierra debajo: al parar el proceso, y al
+ * encontrarla «en proceso» sin nadie detrás en el arranque siguiente.
+ *
+ * Es UNA situación —el turno se cortó a mitad y no hay resultado— pero **tiene dos finales
+ * distintos, y de eso depende lo que reintentar signifique**. `volcar()` corre en el
+ * `finally` del turno, así que un corte a mitad no deja transcript ni entrada en el índice
+ * de sesiones; el hilo del checkpointer, en cambio, puede sobrevivir o no:
+ *  - **Si sobrevive** —hay conversación volcada, así que `sesionAbrible` dice que sí—, el
+ *    agente recuerda el hilo y reintentar CONTINÚA lo que llevaba hecho. Es el texto de
+ *    siempre, y sigue siendo verdad en ese caso.
+ *  - **Si no** —el corte antes de volcar nada—, `olvidarSiNoSePuedeAbrir` acaba de BORRAR
+ *    el checkpoint: un id que no lleva a ninguna parte son además decenas de megas que
+ *    nadie puede alcanzar. Ahí reintentar arranca un hilo nuevo con el encargo entero
+ *    (`AVISO_SIN_HILO_REANUDABLE`), y decir que el agente lo recuerda miente dos veces:
+ *    sobre lo que pasó y sobre lo que va a pasar.
+ *
+ * **De dónde sale que sean dos y no uno.** El texto único se escribió cuando el hilo SÍ
+ * quedaba escrito siempre, y un commit posterior introdujo `olvidarSiNoSePuedeAbrir`, que
+ * lo borra en ese mismo caso. Los dos cambios eran correctos contra su propio encargo; la
+ * contradicción solo se veía leyéndolos juntos. Por eso el motivo se compone DESPUÉS de
+ * saber si el hilo se olvidó, y no antes: quien lo escribe es el único que lo sabe.
+ */
+export declare const MOTIVO_CORTADA_POR_CIERRE: string;
+/**
+ * Por qué está aparcada una tarea que PARÓ la persona (IXCODE-50, `Corredor.cortar(id, {pausa})`).
+ * Dice quién la paró y cómo seguir, en las dos versiones de siempre: con el hilo vivo, «Continuar»
+ * lo retoma; sin él, solo queda empezar de cero.
+ */
+export declare const motivoDePausa: (hiloOlvidado: boolean) => string;
+/** El mismo corte, con el hilo ya olvidado. Ver arriba. */
+export declare const MOTIVO_CORTADA_SIN_HILO: string;
+/** Cuál de los dos, según lo que la regla de `sesion` acabara de decidir. */
+export declare const motivoDeCorteAMitad: (hiloOlvidado: boolean) => string;
+/**
+ * Cuando llega un feedback pero el hilo anterior YA NO se puede reanudar —`Tarea.sesion`
+ * está ausente porque la regla de `sesion` ya lo limpió al no haber nada abrible—, el turno
+ * arranca un hilo NUEVO sin memoria de nada. Mandarle solo el feedback a ese hilo en blanco
+ * sería una frase sin sujeto: «sí, con histórico» no dice nada sin el encargo delante. Así
+ * que se dice la verdad —esto no continúa nada— y se manda el encargo entero al lado. Es
+ * la mitad de «no se finge que continúa» que le toca a esta capa: la otra mitad, que
+ * `sesion` sobreviva siempre que haya algo que abrir, ya está en la regla de `sesion`.
+ */
+export declare const AVISO_SIN_HILO_REANUDABLE: string;
+/**
+ * La petición que se le manda al turno cuando la tarea trae un feedback pendiente.
+ *
+ * **Reanudando, el feedback SOLO** — el mismo patrón que los hallazgos del verificador
+ * (`agent/turno/turnoReal.ts#conVerificacion`): entra como un mensaje de USUARIO más en el hilo
+ * que ya sabe el encargo, lo que se intentó y por qué se aparcó. Repetir el encargo ahí
+ * sería ruido: el modelo ya lo tiene.
+ *
+ * **Sin hilo que reanudar, el encargo entero, con el aviso delante.** Ver
+ * `AVISO_SIN_HILO_REANUDABLE`.
+ */
+export declare const peticionDeFeedback: (encargo: string, texto: string, reanudando: boolean) => string;
+/**
+ * Lo que se espera como mucho a que un turno cortado devuelva, al parar el proceso.
+ *
+ * Generoso pero FINITO: un Ctrl-C que se cuelga para siempre es lo peor que puede hacer este
+ * camino, y el repo ya trata esta clase con tope (el `TOPE_MS` de Codex, los `TOPES_MS` de
+ * los dispositivos). Al agotarse no se miente diciendo que se paró: la tarea se queda «en
+ * proceso» y la reconciliación del siguiente arranque la aparca, que es justo para lo que
+ * existe.
+ */
+export declare const TOPE_DE_PARADA_MS = 30000;
+/**
+ * Lo que se espera, como MUCHO, a que el juez de QA conteste.
+ *
+ * Es la regla de siempre en este repo —«cada proceso lleva tope», y «un cuelgue se dice
+ * como *no respondió*, nunca se queda el panel en *consultando…*»— aplicada a una llamada
+ * de modelo: los SDK traen plazos por omisión del orden de diez minutos, y durante todo ese
+ * rato la tarea diría «en proceso» ocupando el hueco y el proyecto sin que nadie pueda
+ * saber por qué. Dos minutos es de sobra para un veredicto de dos frases sobre una lista de
+ * nombres.
+ *
+ * Al agotarse NO se entrega: la consulta se abandona (la llamada sigue viva en segundo
+ * plano, no hay con qué abortarla desde aquí) y la tarea queda esperando feedback con el
+ * motivo — que es lo mismo que hace `parar()` cuando su plazo se agota: no mentir.
+ */
+export declare const TOPE_DEL_JUEZ_MS = 120000;
+/** Lo que el corredor necesita de una consola de proyecto abierta para una tarea. */
+export interface ConsolaParaTarea {
+    raiz: string;
+    idDeHilo: string;
+    /**
+     * Corre el encargo.
+     *
+     * `aparcar` es lo que la consola de tarea llama al toparse con algo que necesita a una
+     * persona; `autorizado` es lo que llama al AUTORIZAR escrituras sin aprobación, con las
+     * rutas relativas. Los dos son callbacks y no un valor de retorno porque el turno puede
+     * LANZAR después de haber autorizado —eso es justo lo que hace `preguntar`—, y un retorno
+     * se perdería con la excepción. `autorizado` puede llamarse varias veces: un turno
+     * autoriza en varias rondas de aprobación.
+     */
+    correrTarea(encargo: string, aparcar: (motivo: string) => void, autorizado?: (ficheros: readonly string[]) => void): Promise<ResultadoDeTurno | void>;
+    cerrar(): Promise<void>;
+    /**
+     * Espera a que la marca de git de la sesión esté escrita.
+     *
+     * Opcional porque los dobles de test no la tienen, y su ausencia es inofensiva: lo único
+     * que pasa es que la medida de «revisable» puede llegar antes que la ref. En producción
+     * la aporta `consolaParaTarea`, y es lo que cierra una carrera MEDIDA — sin ella
+     * `cambiosDeSesion` decía `sin-marca` y TODA tarea se aparcaba diciendo que nadie podía
+     * revisarla. La espera vive aquí y no en `cerrar()` para no cobrársela a quien cierra un
+     * proyecto estando sentado delante.
+     */
+    esperarMarca?(): Promise<void>;
+    /**
+     * Engancha a alguien que MIRA en vivo lo que hace este turno, y devuelve el transcript de
+     * ese instante. Opcional porque los dobles de test no lo tienen; su ausencia solo
+     * significa que esa consola no se puede mirar.
+     *
+     * **Lo que se mira son los actos de SU sesión, no un registro nuevo.** Son los mismos que
+     * `volcar()` escribe en el `.jsonl`, así que la vista en vivo y el transcript que se lee
+     * al abrir la sesión después son lo MISMO — la misma regla que la lista de artefactos,
+     * que sale de los actos y nunca del disco.
+     *
+     * En producción esto reenvía a `ConsolaWeb.mirar` y **no** a `conectar`: con `conectar`,
+     * el `eof()` de esa consola pasaría a decir que hay un humano al que preguntar (medido), y
+     * la consola de una tarea es justo la que no tiene a nadie.
+     */
+    mirar?(enviar: Sumidero): readonly Acto[];
+    /** Se va UN mirón. Los demás siguen: dos personas pueden mirar la misma tarea. */
+    dejarDeMirar?(enviar: Sumidero): void;
+}
+export interface Corredor {
+    arrancar(): Promise<void>;
+    /** Corta lo que esté en vuelo —un turno tarda minutos— y suelta el cerrojo si es nuestro. */
+    parar(): Promise<void>;
+    /**
+     * Corta el turno de ESA tarea si corre AQUÍ, sin tocar las demás — es `parar()` acotado a
+     * una sola entrada. Task 14: `descartar` lo llama ANTES de borrar, porque sin esto el
+     * turno seguía corriendo (y escribiendo en el proyecto) después de que la tarea
+     * desapareciera del kanban, sin que ninguna pantalla lo dijera.
+     *
+     * **Devuelve si se puede seguir** — `true` también cuando no había NADA que cortar (la
+     * tarea no corre en este proceso: no está en `enVuelo`, así que borrarla es seguro sin
+     * esperar nada). `false` solo cuando SÍ corría aquí y no soltó el proyecto dentro del
+     * plazo (`TOPE_DE_PARADA_MS`, el mismo de `parar()`): quien llama tiene que leerlo como
+     * «no está seguro borrar todavía», nunca como «bórrala igual» — un turno que sigue
+     * escribiendo no puede perder también su carpeta de adjuntos por debajo.
+     *
+     * Espera a `EnVuelo.trabajo` entero, no solo a que `cortar()` dispare el abort: son dos
+     * cosas distintas y solo la segunda dice que la consola SOLTÓ su montaje de `/adjuntos/`
+     * — antes de eso, borrar esa carpeta es quitarle el suelo a un turno vivo.
+     */
+    cortar(id: string, opciones?: {
+        pausa?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Engancha a quien quiere MIRAR en vivo lo que hace una tarea, y devuelve su transcript
+     * hasta ese instante.
+     *
+     * `undefined` = esa tarea no corre en este proceso (ya acabó, o la ejecuta el otro
+     * corredor, que este no puede alcanzar). **No es `[]`**: una lista vacía significaría
+     * «corre y todavía no ha pintado nada», y confundirlas dejaría una pantalla esperando
+     * para siempre los actos de un turno que no existe.
+     *
+     * Es de SOLO lectura por construcción: por aquí no entra nada hacia el turno, solo sale
+     * lo que ya se está guardando en el transcript de su sesión.
+     */
+    mirar(id: string, enviar: Sumidero): readonly Acto[] | undefined;
+    /** Se va UN mirón de esa tarea. Los demás siguen mirándola. */
+    dejarDeMirar(id: string, enviar: Sumidero): void;
+    /** ¿Ejecuta ESTE proceso? Falso si el cerrojo lo tiene otro, o si lo hemos perdido. */
+    corriendoAqui(): boolean;
+    /**
+     * ¿Lo ejecuta OTRO proceso? `undefined` = no se ha podido mirar.
+     *
+     * Es la otra mitad de `corriendoAqui`, y sin ella la interfaz no puede distinguir dos
+     * cosas que significan lo contrario: **«no soy yo» manda a esperar y «no hay nadie» dice
+     * que no va a pasar nada** hasta que alguna consola tome el relevo. Un aviso que manda a
+     * esperar a un proceso que no existe es peor que uno mudo.
+     *
+     * Los tres valores salen de lo MEDIDO en `tomarCerrojo`, y ninguno se deduce: `true` si
+     * el cerrojo lo tenía otro (o si lo hemos perdido en marcha), `false` si lo tomamos
+     * nosotros —aunque después lo hayamos soltado, que es cómo «nadie» es alcanzable de
+     * verdad: el arranque revienta tras tomarlo— y `undefined` si ni se pudo consultar (un
+     * `~/.xonecode/tareas` que no se puede escribir). **El pid NO sale de aquí**: es un dato
+     * de la máquina, no le dice nada a quien lo lee, y este valor viaja por el cable.
+     */
+    ejecutaOtroProceso(): boolean | undefined;
+    /** Vuelve a mirar la cola: se llama al crear una tarea, al terminar una, y al abrir o
+     *  cerrar un proyecto (que es lo que bloquea y desbloquea su raíz). */
+    revisar(): void;
+    /** Para los tests: espera a que se asiente lo que el lazo tenga lanzado. */
+    asentar(): Promise<void>;
+}
+/**
+ * Del `ConsolaDeProyecto` que abre el vestíbulo al `ConsolaParaTarea` que el corredor pide.
+ *
+ * Aquí se junta todo: la segunda puerta (que no mueve el cable), la consola que APARCA en
+ * vez de contestar por nadie, y el ejecutor de siempre — el mismo que corre un turno de una
+ * persona, con las mismas barreras.
+ *
+ * **Vive aquí y no en el cierre de `arranque.ts`** —donde el plan la puso— por una razón
+ * medible: desde ahí no se puede llamar, y la propiedad que sostiene (que la sesión de la
+ * tarea se GUARDE) es justo la que se rompe en silencio. El `MEDIDO:` de `vestibulo.test.ts`
+ * no la vigila: el agujero está en qué piel se le pasa, así que ese test se queda verde
+ * tanto con el arreglo como sin él.
+ *
+ * **La PIEL es la que hace que el turno se guarde**, y es el único motivo de que esta
+ * función sea algo más que tres campos reenviados. `volcar()` (`vestibulo.ts`) lee los actos
+ * de la consola de PROYECTO, así que un turno corrido con una `Consola` ajena no vuelca
+ * nada: la conversación se pinta en un objeto que nadie lee y la tarea acaba con su sesión
+ * vacía. Pasándole `consola.consola.consola.piel` —la misma que usa una persona— el turno
+ * escribe actos de asistente, de razonamiento y las tarjetas de artefacto en el transcript
+ * de SU sesión, que es lo que hace que atender la tarea sea abrir su conversación.
+ */
+export declare function consolaParaTarea(consola: ConsolaDeProyecto): ConsolaParaTarea;
+export declare function crearCorredorDeTareas(opciones: {
+    disco: TareasEnDisco;
+    /**
+     * Trae la pantalla de Stitch ELEGIDA para la tarea (`Tarea.pantallaDeStitch`) a la carpeta de artefactos de su sesión,
+     * ANTES del primer turno, y devuelve la línea para el encargo (`core/stitch.ts#textoDePantallaElegida`). Nunca lanza.
+     * Ausente = esta ejecución no tiene conectores: el encargo dice con qué `name` traerla.
+     */
+    prepararDiseno?: (raiz: string, sesion: string, pantalla: PantallaElegida) => Promise<string>;
+    /**
+     * Abre el proyecto para una tarea — y con `sesion`, lo REABRE con esa exacta, que es lo
+     * que hace que reanudar (un reintento, o un feedback) siga la MISMA conversación en vez
+     * de abrir una en blanco.
+     *
+     * `construirConsolaDeProyecto` (`vestibulo.ts`) ya hace lo que hace falta con `sesion`
+     * pasada — reabre el índice de la sesión, decide `idSesion = sesion` en vez de un
+     * `randomUUID()`, y el `thread_id` del checkpointer sale de ahí—, así que esto solo tiene
+     * que REENVIAR lo que la tarea ya sepa. `undefined` en la primera ejecución sigue dando
+     * una sesión nueva, igual que siempre.
+     */
+    abrirParaTarea: (raiz: string, sesion?: string, adjuntos?: string, tarea?: string) => Promise<ConsolaParaTarea>;
+    /** Se lee en cada pasada: cambiar el tope en Ajustes tiene que notarse sin reiniciar. */
+    concurrencia: () => number;
+    /**
+     * SIEMBRA la marca de tarea en el índice de sesiones de un proyecto
+     * (`sesiones.ts#marcarTareaDeSesion`). Se llama al arrancar, una vez por tarea que ya
+     * tenga sesión, y existe solo por las sesiones anteriores a esa marca: sin ella, la
+     * primera sesión de tarea de cada proyecto se queda pintada como una conversación para
+     * siempre. Ausente = esta ejecución no siembra nada, y las viejas se quedan sin marcar,
+     * que es el lado conservador.
+     */
+    marcarSesionDeTarea?: (raiz: string, sesion: string, tarea: string) => void;
+    /**
+     * Las raíces donde NO se puede arrancar nada ahora mismo: hoy, la del proyecto que tiene
+     * abierto una persona. Se lee en cada pasada por lo mismo que la concurrencia — abrir y
+     * cerrar un proyecto no reinicia nada. Ver `siguientesAEjecutar#bloqueados` para el por
+     * qué («gana la persona»).
+     */
+    bloqueados?: () => readonly string[];
+    /**
+     * ¿Hay algo que una persona pueda ABRIR con ese id de sesión? O sea: ¿está en el índice
+     * de sesiones del proyecto, con su transcript volcado?
+     *
+     * Ausente = **no se sabe**, y entonces no se toca nada: quitar la `sesion` y olvidar un
+     * hilo son destructivos, así que sin nadie que pueda afirmar que no hay nada abrible se
+     * conserva — la misma dirección conservadora que `historica` cuando no se le puede
+     * preguntar al checkpointer. Ver `conSesionSoloSiSePuedeAbrir`.
+     */
+    sesionAbrible?: (raiz: string, sesion: string) => boolean;
+    /** Olvida el hilo del agente de una sesión que no nombra nada abrible
+     *  (`agent/sesiones/checkpointer.ts#olvidarHilo`). Ver `conSesionSoloSiSePuedeAbrir`. */
+    olvidarHilo?: (raiz: string, sesion: string) => Promise<void>;
+    /**
+     * Cuánto se espera, como MUCHO, a que los turnos cortados devuelvan en `parar()`. Entra
+     * por parámetro como el `msDeEspera` de la consola web y por lo mismo: `npm test` no puede
+     * esperar un tope de verdad. Ver `TOPE_DE_PARADA_MS`.
+     */
+    esperaAlParar?: number;
+    /** Cuánto se espera al juez. Por parámetro por lo mismo que `esperaAlParar`: `npm test`
+     *  no puede esperar un tope de verdad. Ver `TOPE_DEL_JUEZ_MS`. */
+    esperaDelJuez?: number;
+    pid?: number;
+    /** Se llama en cada cambio, para que el cable emita la cola nueva. */
+    alCambiar?: (tareas: readonly Tarea[]) => void;
+    /**
+     * A dónde van los avisos SOBRE ESTE PROCESO —«las tareas las ejecuta otro»—, y solo
+     * esos. Lo que le pasa a una TAREA no sale por aquí: `informar` escribe un acto de
+     * sistema en la pantalla de una persona, y el sitio de un fallo de tarea es el registro
+     * de la tarea (su `motivo`, y su transcript). Un aviso sobre la tarea de otro proyecto
+     * en medio de la conversación de alguien es ruido que además no es accionable ahí.
+     */
+    informar?: (texto: string) => void;
+    /**
+     * El juez de QA que decide si el trabajo hace lo que se pedía.
+     *
+     * **Es OBLIGATORIO, fail-closed por TIPO**, igual que `PoliticaDeAprobacion` en
+     * `core/cloudstudio.ts`: «no se puede invocar sin decir quién autoriza». Un puerto
+     * opcional con omisión conservadora compilaría sin el cableado de producción, y entonces
+     * la pieza estaría sin montar con todo en verde — que es exactamente el agujero que
+     * `construirCorredorDeTareasCableado` y `backendDeAgente` existen para cerrar.
+     */
+    juez: JuezDeTareaPort;
+    /**
+     * ¿Se puede REVISAR lo que la tarea escribió en esa sesión?
+     *
+     * En producción es `cambiosDeSesion(raiz, sesion).via === "git"` — la MISMA función que
+     * pinta la pestaña Revisión, no una parecida, así que «revisable» significa literalmente
+     * «Revisión lo enseña». Entra por parámetro porque es git y `npm test` no puede
+     * necesitarlo en cada caso.
+     *
+     * **No es «el árbol está limpio», y eso está medido**: una tarea que escribe un fichero
+     * deja el árbol sucio por definición (`git status --porcelain` → `?? Clientes.xne`), así
+     * que con esa condición ninguna tarea se entregaría nunca. Ver `core/entrega.ts`.
+     *
+     * Devuelve DOS cosas y no una porque las dos salen de la misma pregunta a git: si hay
+     * «antes» con que comparar, y **cuántos ficheros cambió la sesión** — de lo segundo
+     * depende que una tarea de solo lectura se pueda entregar, y tiene que salir de git y no
+     * de `autorizadas` (ver `MedidaDeEntrega.escribio`).
+     */
+    revisable: (raiz: string, sesion: string) => Promise<RevisionDeSesion>;
+}): Corredor;

package/dist/web/servidor/datosDeCierre.d.ts

@@ -0,0 +1,4 @@
+import type { DatosDeCierre } from "../../core/gestorDeTareas.js";
+/** Compone `DatosDeCierre` desde el disco real del proyecto: git para lo que cambió, el
+ *  `.jsonl` de la sesión para el veredicto y la última respuesta. */
+export declare function datosDeCierre(raiz: string, id: string): Promise<DatosDeCierre>;

package/dist/web/servidor/interrupcion.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Esperar a que alguien pare la consola web, y que pararla sea un cierre ORDENADO.
+ *
+ * El cierre ordenado ya existía (`arrancarConsolaWeb`: corredor, vestíbulo, servidor): aborta
+ * cada turno en vuelo, su `finally` escribe la foto de memoria y la consola vuelca el chat al
+ * `.jsonl`. Lo frágil era la ESPERA: con `process.once`, una segunda señal no tenía oyente y
+ * node aplicaba su acción por omisión —matar en seco a mitad del cierre—.
+ *
+ * Cuándo llega esa segunda señal, medido: cuando un `npm run <script>` cuyo comando es `tsx …`
+ * A SECAS recibe un Ctrl-C, node recibe dos SIGINT —el del grupo del terminal y el que reenvía
+ * npm unos 30 ms después—, y un cierre más largo que eso moría con 130. Con el `npm run web` de
+ * hoy (`npm run build:web && tsx …`) NO pasa: el `sh` que el `&&` deja en medio se queda el
+ * reenvío, y un cierre de 3 s sobrevive; tampoco con `./bin/xonecode` (`exec tsx`). Es una
+ * guarda contra quitar ese `&&`, y lo que añade de verdad es el aviso y la salida forzada.
+ *
+ * Tres reglas:
+ * - La PRIMERA señal empieza el cierre y lo DICE, con la salida forzada al lado.
+ * - Una señal dentro de `VENTANA_DE_SENAL_REPETIDA_MS` es el reenvío: se ignora.
+ * - Una posterior es alguien que insiste: un cierre colgado tiene que tener salida, y se
+ *   FUERZA con el código de la señal (130 SIGINT, 143 SIGTERM).
+ *
+ * Los oyentes se quedan puestos a propósito hasta que el proceso sale: quitarlos devolvería
+ * a node la acción por omisión justo cuando más falta hace no tenerla.
+ */
+/** Cuánto después de la primera señal una igual se toma por el reenvío de npm (medido: ~30 ms). */
+export declare const VENTANA_DE_SENAL_REPETIDA_MS = 1000;
+type Senal = "SIGINT" | "SIGTERM";
+export interface OpcionesDeInterrupcion {
+    /** De dónde llegan las señales. Por omisión, `process`. */
+    fuente?: {
+        on(senal: Senal, oyente: () => void): unknown;
+    };
+    ahora?: () => number;
+    /** Salir YA. Por omisión, `process.exit`. */
+    forzar?: (codigo: number) => void;
+    avisar?: (texto: string) => void;
+}
+export declare function esperarInterrupcion(opciones?: OpcionesDeInterrupcion): Promise<void>;
+export {};

package/dist/web/servidor/pielWeb.d.ts

@@ -0,0 +1,32 @@
+import type { Piel } from "../../core/turno.js";
+import type { Acto } from "../../core/actos.js";
+import type { ConsumoDeTurno } from "../../core/actos.js";
+export interface PielWeb {
+    piel: Piel;
+    /** La lista de actos, para el transporte y para la persistencia. */
+    actos: () => readonly Acto[];
+    /**
+     * Se llama con cada acto nuevo: es por donde el transporte lo emite. También se
+     * llama cuando el último acto es un `herramientas` que se ACTUALIZA en vez de crecer
+     * —el cierre de una racha sustituyendo su apertura, la misma regla de `conLineaDeTool`—:
+     * sin ese aviso, un transporte que solo escuchara altas mostraría para siempre la línea
+     * de apertura de la racha. Un consumidor que reciba dos `herramientas` seguidos
+     * sustituye el último por el nuevo; cualquier otro tipo se añade.
+     */
+    alActo: (escucha: (acto: Acto) => void) => void;
+}
+export declare function crearPielWeb(ahora?: () => number, 
+/**
+ * Lo consumido ACUMULADO por la sesión, si consta. Es el mismo cierre que la consola ya
+ * tiene (`ConsolaDeProyecto.consumo`, que pregunta a la sesión real), y entra aquí para
+ * que el `fin` pueda llevar el DELTA del turno sin que `core/turno.ts` sepa nada de
+ * consumo: la piel lo consulta al cerrar, no el motor al llamarla.
+ *
+ * Va inyectado y no leído de un cierre propio porque la sesión real llega TARDE —nace
+ * dentro del primer turno—, así que lo que se guarda es la PREGUNTA, no la respuesta.
+ *
+ * Ausente = esta piel no persiste consumo, y entonces el `fin` sale sin `consumo`, que es
+ * «no consta». Las otras dos pieles ni lo reciben: por eso `Piel.fin(ms)` no cambia de
+ * firma y stdio y la TUI siguen byte-idénticas.
+ */
+consumoAcumulado?: () => ConsumoDeTurno | undefined): PielWeb;

package/dist/web/servidor/puenteRemoto.d.ts

@@ -0,0 +1,80 @@
+/**
+ * La sesión remota: cada MÓVIL conectado por el puente es un sumidero más del cable, enganchado
+ * por la MISMA puerta que una pestaña SSE (`engancharCliente`/`soltarCliente`). Así recibe la
+ * misma ráfaga al entrar, sigue a la consola en foco cuando se muda y cuenta como «hay alguien
+ * delante» igual que una pestaña. Lo que sale pasa `filtrarSalida`; lo que entra,
+ * `validarEntradaDelMovil`, y se despacha por las mismas funciones que `POST /accion`.
+ *
+ * **Por la vía ngrok, el puente va a la dirección de un TÚNEL** (`tunel`), que se abre al
+ * encender y se cierra en todo final —apagar, un canal que se cierra solo, la caída del propio
+ * túnel—, salvo al REVOCAR: la sala y el secreto son nuevos y la dirección pública la misma, y
+ * un segundo ngrok de la misma cuenta lo rechazaría el propio ngrok. Su caída se escucha por
+ * IDENTIDAD del túnel y no por generación, porque sobrevive a la generación que lo abrió.
+ */
+import type { PuenteRemotoPort, TunelAbierto } from "../../core/ports.js";
+import type { Panorama } from "../../core/panorama.js";
+import { type EntradaDelMovil, type MensajeDeArtefactoAlMovil } from "../../core/remoto.js";
+import type { Sumidero } from "./transporte.js";
+export type EstadoDeSesionRemota = {
+    estado: "apagada";
+} | {
+    estado: "abriendo";
+} | {
+    estado: "activa";
+    url: string;
+    moviles: number;
+}
+/** Sin `url`: el relé no contestó nunca (inalcanzable) y se sigue intentando. Se puede apagar. */
+ | {
+    estado: "reconectando";
+    url?: string;
+    moviles: number;
+} | {
+    estado: "error";
+    motivo: string;
+};
+export interface OpcionesDeSesionRemota {
+    /** `undefined` = el paquete no está instalado. Solo se llama al encender. */
+    puerto: () => Promise<PuenteRemotoPort | undefined>;
+    servidor: () => string;
+    /**
+     * El túnel de ESTE encendido, preguntado en cada `encender`: `undefined` = vía servidor
+     * (`servidor()`), y con valor el puente va a `TunelAbierto.servidor`. Un fallo suyo cruza solo
+     * si su texto es de `MOTIVOS_DEL_TUNEL`.
+     */
+    tunel?: () => {
+        abrir(): Promise<TunelAbierto>;
+    } | undefined;
+    engancharCliente(sumidero: Sumidero): void;
+    soltarCliente(sumidero: Sumidero): void;
+    despachar(mensaje: EntradaDelMovil): void;
+    /**
+     * Un móvil acaba de entrar (ya enganchado): `enviar` le escribe SOLO a él, por el mismo filtro y
+     * tope que su sumidero. Es por donde le llega su primer `panorama`, que no va a las pestañas.
+     */
+    alEntrarMovil?(enviar: (mensaje: Panorama) => void): void;
+    informar(texto: string): void;
+    alCambiar(estado: EstadoDeSesionRemota): void;
+    /** Solo para los tests, que no quieren fabricar 700 kB: por omisión `TOPE_DE_SALIDA_BYTES`. */
+    topeDeSalida?: number;
+}
+export interface SesionRemota {
+    encender(): Promise<void>;
+    revocar(): Promise<void>;
+    /** Resuelve cuando el túnel, si lo había, está cerrado: el cierre de la consola lo espera. */
+    apagar(): Promise<void>;
+    estado(): EstadoDeSesionRemota;
+    /** ¿Hay algún móvil dentro? Para no componer un `panorama` que no leería nadie. */
+    hayMoviles(): boolean;
+    /**
+     * A TODOS los móviles y a nadie más: el `panorama` y los trozos de un artefacto pedido desde el
+     * móvil no son de las pestañas, así que no pasan por `clientes` sino por los móviles de esta
+     * sesión, con el filtro y el tope de siempre.
+     */
+    difundir(mensaje: Panorama | MensajeDeArtefactoAlMovil): void;
+}
+export declare const MOTIVO_NO_ABRIO = "no se pudo abrir la sesi\u00F3n remota";
+export declare const SIN_PAQUETE = "la sesi\u00F3n remota no est\u00E1 disponible en esta instalaci\u00F3n";
+/** Lo que ngrok o el sistema digan no cruza: solo un texto nuestro, o el genérico. */
+export declare const motivoFijoDelTunel: (texto: unknown) => string;
+export declare function crearSesionRemota(o: OpcionesDeSesionRemota): SesionRemota;

package/dist/web/servidor/servidor.d.ts

@@ -0,0 +1,53 @@
+/**
+ * El servidor de la consola web: `node:http`, loopback, sin framework.
+ *
+ * Tres cosas son de seguridad y no de estilo:
+ *  - **Loopback y nada más.** No hay bandera para `0.0.0.0`: un servidor local que abre
+ *    la red expone el proyecto entero del usuario y su `auth.json` está a un bug de
+ *    distancia.
+ *  - **`Host` y `Origin` en TODA petición.** El ataque real a un servidor local no es que
+ *    alguien escanee el puerto: es DNS rebinding, donde una web cualquiera resuelve su
+ *    dominio a 127.0.0.1 y le habla a este proceso desde el navegador de la víctima. Un
+ *    `Host` que no sea loopback, o un `Origin` que no sea el nuestro, es 403.
+ *  - **`.xonecode` no se sirve NUNCA.** Ni el del proyecto ni el del home. Va antes que
+ *    la comprobación de existencia, para que un 403 y un 404 no cuenten cosas distintas.
+ */
+import { type IncomingMessage, type ServerResponse } from "node:http";
+export type ManejadorRuta = (peticion: IncomingMessage, respuesta: ServerResponse) => void | Promise<void>;
+export interface ServidorWeb {
+    readonly puerto: number;
+    /** La dirección de bind REAL (`servidorHttp.address().address`), no una construida. */
+    readonly direccion: string;
+    readonly token: string;
+    readonly url: string;
+    /** Registra un manejador propio para `MÉTODO ruta` — usado por tareas futuras (SSE, acciones). */
+    registrarRuta(metodo: string, ruta: string, manejador: ManejadorRuta): void;
+    /**
+     * Registra un manejador para `MÉTODO ruta` que se atiende SIN cookie ni `?t=`: solo tras
+     * las comprobaciones de `Host` y `Origin`, que siguen delante igual que para cualquier
+     * otra ruta. Es para el callback OAuth de un conector: la cookie es `SameSite=Strict`, así
+     * que una redirección que llega desde el proveedor viene SIN ella y se quedaría en un 401
+     * antes de que el propio callback pudiera decidir nada. La autenticación de una ruta
+     * pública la pone su manejador (un `state` de un solo uso), nunca esta función.
+     */
+    registrarRutaPublica(metodo: string, ruta: string, manejador: ManejadorRuta): void;
+    cerrar(): Promise<void>;
+}
+interface OpcionesServidor {
+    puerto: number;
+    raizEstaticos: string;
+    /**
+     * Un anfitrión EXTRA que se acepta además del loopback, para un túnel (ngrok, Tailscale)
+     * que apunte a este proceso. Es una lista de uno y sin comodines a propósito: el
+     * comprobante de `Host` es la única defensa contra el DNS rebinding, y «lo que acabe en
+     * .ngrok-free.app» la deja abierta a cualquiera que se registre en ngrok.
+     *
+     * El puerto NO se le añade: un túnel HTTPS llega con `Host: algo.ngrok-free.app`, sin
+     * puerto, mientras que el loopback llega con el suyo. Se compara tal cual.
+     *
+     * Ausente = solo loopback, que es como debe estar salvo que alguien lo pida a propósito.
+     */
+    anfitrion?: string;
+}
+export declare function arrancarServidor(opciones: OpcionesServidor): Promise<ServidorWeb>;
+export {};