xonecode 0.38.44 → 0.39.4

package/dist/core/tareasDelPlan.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Lo que un `TASKS.md` dice de sus tareas, leído como DATO para la pestaña Planes.
+ *
+ * El formato lo fija la skill `xone-plan-builder` (`references/TASKS-FORMAT.md`): una sección
+ * `### NN — Título` por tarea, con `**Bloqueada por:**` y casillas `- [ ]` de criterios, más el
+ * `**Estado:**` que el prompt del desarrollador le pide actualizar (`agentesEnDisco.ts`).
+ *
+ * **Es lo que el plan DICE, no lo que se midió**: el estado y las casillas las marca el modelo.
+ * Por eso quien lo pinta lo rotula «según el plan», y por eso este lector es conservador:
+ *
+ * - Una dependencia solo se reconoce cuando es un NÚMERO de tarea (`02`, `02, 04`) o un RANGO
+ *   (`01–07`); el resto de la línea se conserva como texto tal cual, que es donde el analista
+ *   escribe cosas como «requiere ejecución externa». Inventarle una estructura a esa prosa
+ *   sería afirmar algo que el plan no dice.
+ * - El estado se DEVUELVE como está escrito; no se normaliza a un enum. Un «bloqueada», un
+ *   «en curso» o un «hecha» son palabras del plan, y traducirlas sería decidir por él.
+ * - Un fichero sin ninguna sección con forma de tarea no es un plan vacío: `tareas` va vacío y
+ *   quien lo pinta enseña el texto entero.
+ * - La cabecera se reconoce también en la forma que el modelo escribe a veces fuera del formato,
+ *   `## T1 — Título` (nivel 2, prefijo `T`): visto en un plan real que la pestaña pintaba como
+ *   «sin tareas» con siete dentro. El número se conserva TAL CUAL (`T1`), porque es lo que
+ *   citan sus «Bloqueada por». Con ese prefijo solo cuenta como dependencia un número que lo
+ *   lleve: «T2 (resuelta la PENDIENTE 3)» es T2, no T2 y 3.
+ */
+export interface TareaDelPlan {
+    /** El número tal como aparece (`01`), que es lo que citan las dependencias. */
+    numero: string;
+    titulo: string;
+    /** El `**Estado:**` tal cual, o ausente si la tarea no lo lleva. */
+    estado?: string;
+    /** Las tareas que la bloquean, reconocidas como números (rangos ya expandidos). */
+    bloqueadaPor: string[];
+    /** La línea «Bloqueada por» entera, para enseñarla cuando lleva algo más que números. */
+    bloqueadaPorTexto?: string;
+    criterios: {
+        hechos: number;
+        total: number;
+    };
+    /** Por dónde va, CALCULADO del estado y las casillas (`progresoDeTarea`). */
+    progreso: ProgresoDeTarea;
+    /** El markdown de la sección, sin su cabecera: la ficha que se abre al pulsarla. */
+    cuerpo: string;
+}
+/**
+ * Las cuatro palabras con que se escribe `**Estado:**` (`xone-plan-builder`, `TASKS-FORMAT.md`):
+ * quien desarrolla pone `implementada` al escribir el código y `hecha` cuando lo comprobó.
+ */
+export declare const ESTADOS_DE_TAREA: readonly ["pendiente", "en curso", "implementada", "hecha"];
+export type EstadoDeTarea = (typeof ESTADOS_DE_TAREA)[number];
+/**
+ * Por dónde va una tarea, que es lo que la pestaña resume.
+ *
+ * - `finalizada`: TODAS sus casillas marcadas —cada una es un criterio COMPROBADO—, o `hecha`
+ *   sin casillas que marcar.
+ * - `implementada`: el código está (`implementada` o `hecha`) pero le falta comprobar algo. También
+ *   con ALGUNA casilla marcada, diga lo que diga su estado: un criterio comprobado es código que
+ *   existe, y un plan real marca casillas sin escribir `**Estado:**` por tarea —con 2 de 3
+ *   comprobados, el círculo salía vacío, como si no se hubiera empezado—.
+ * - `en-curso` y `pendiente`: lo que dice su estado; un estado que no se reconoce cuenta como
+ *   pendiente, porque afirmar avance que el plan no dice sería peor que quedarse corto.
+ */
+export type ProgresoDeTarea = "pendiente" | "en-curso" | "implementada" | "finalizada";
+/**
+ * El estado del plan como una de las cuatro palabras, mirando solo cómo EMPIEZA: un plan real
+ * escribe «implementada — sin verificar en la app» o «pendiente — **NO hecha**», y lo que
+ * cuenta es la primera palabra, no la prosa de detrás (que tiene un «hecha» dentro).
+ */
+export declare function estadoReconocido(estado: string | undefined): EstadoDeTarea | undefined;
+export declare function progresoDeTarea(estado: string | undefined, criterios: {
+    hechos: number;
+    total: number;
+}): ProgresoDeTarea;
+export interface TareasDelPlan {
+    /** El `# …` del principio, si lo hay. */
+    titulo?: string;
+    tareas: TareaDelPlan[];
+}
+/**
+ * Si una línea abre una tarea, en cualquiera de las formas que se han visto, y lo que sobra en esa
+ * MISMA línea (en la forma de viñeta, `Bloqueada por: …` suele ir ahí). El formato de la skill
+ * (`### 01 — Título`) manda; las otras son tolerancia, no un segundo formato.
+ */
+export declare function cabeceraDeTarea(l: string): {
+    numero: string;
+    titulo: string;
+    resto?: string;
+} | undefined;
+/** «Ninguna …» o «nada»: la forma de decir que puede empezar ya. */
+export declare const SIN_DEPENDENCIAS: RegExp;
+/**
+ * Los números de tarea que nombra una línea «Bloqueada por». Un rango `01–07` (con guion,
+ * raya o «a») se expande con el ancho del primero; «Ninguna» no nombra ninguno.
+ */
+export declare function dependenciasDe(linea: string, conPrefijo?: boolean): string[];
+export declare function leerTareasDelPlan(texto: string): TareasDelPlan;
+/** La ruta del `TASKS.md` de un plan: `/planes/<slug>/TASKS.md`. */
+export declare const RUTA_DE_TASKS: RegExp;
+/**
+ * Por qué NO vale un `TASKS.md` que se va a escribir entero, o `undefined` si vale: tiene que reconocerse al menos una
+ * tarea, y CADA tarea tiene que traer sus criterios como casillas `- [ ]`.
+ *
+ * Existe por una medida: en cinco pasadas de la misma calculadora el analista escribió las casillas en tres y en dos
+ * (calc10, calc13) no, con los criterios como viñetas sueltas. Sin casillas, quien comprueba en el aparato no puede marcar
+ * nada (`marcarCriterios` solo cambia `- [ ]`), el plan no dice por dónde va y la pestaña Planes no enseña progreso. El
+ * prompt ya pedía el formato; era texto. Se aplica al ESCRIBIR el fichero entero, no al editarlo: un plan viejo sin
+ * casillas se puede seguir anotando.
+ */
+export declare function motivoDeTasksInaceptable(texto: string): string | undefined;
+/**
+ * Marca como COMPROBADOS unos criterios de una tarea: cambia sus `- [ ]` a `- [x]`, contando las
+ * casillas de la sección de 1 en adelante, en el orden en que aparecen.
+ *
+ * Es lo que usa quien COMPRUEBA en el aparato (`marcar_criterios_del_plan`) y no puede escribir
+ * ficheros: por eso toca SOLO las casillas de UNA tarea, y nada más del fichero cambia. Un número
+ * que no existe se rechaza entero —marcar la mitad dejaría al modelo creyendo que marcó todo—.
+ */
+export declare function marcarCriterios(texto: string, numero: string, criterios: readonly number[]): {
+    texto: string;
+    marcados: number[];
+    yaEstaban: number[];
+} | {
+    error: string;
+};

package/dist/core/tareasEnElGestor.d.ts

@@ -0,0 +1,117 @@
+import type { CategoriaDeTarea, ComentarioDelGestor, EstadoDelGestor, GestorDeTareasPort, MapeoDeEstados, TareaDelGestor, TransicionDelGestor, Vinculo } from "./gestorDeTareas.js";
+import type { EstadoDeTarea, Tarea, TicketDeTarea } from "./tareas.js";
+/**
+ * La cabecera FIJA del comentario con el encargo ampliado. Es una constante porque la fase 2 la BUSCARÁ entre los
+ * comentarios del ticket para leer el último encargo revisado: cambiarla dejaría de encontrar los de antes.
+ */
+export declare const CABECERA_DEL_ENCARGO = "\uD83E\uDD16 Encargo para el agente (xonecode)";
+/** El comentario que sube el encargo ampliado al ticket recién creado. Markdown: los dos gestores lo entienden. */
+export declare function comentarioDeEncargo(encargo: string): string;
+/**
+ * Qué hay que escribir en el gestor cuando una tarea cambia de estado. Solo dos momentos en la fase 1:
+ *  - **empezar** (→ `en-proceso`): pasar el ticket a EN CURSO. Vuelve a pasar tras cada feedback y tras una
+ *    reanudación, así que quien lo aplica mira antes si el ticket ya está en curso (`hayQueTransicionar`).
+ *  - **cerrar** (→ `terminada`): el comentario de cierre y la transición a PROBAR.
+ * Aparcar (→ `requiere-atencion`) no escribe nada todavía; volver a la cola (→ `nuevo`) tampoco.
+ */
+export declare function escrituraEnElGestor(antes: EstadoDeTarea | undefined, despues: EstadoDeTarea): "empezar" | "cerrar" | undefined;
+/** Un cambio que hay que reflejar: la tarea tal como quedó y qué escribir. */
+export interface ReflejoPendiente {
+    tarea: Tarea & {
+        ticket: TicketDeTarea;
+    };
+    /** `descartar` no sale de un cambio de estado sino de BORRAR la tarea (ver `conReflejoAlGuardar`). */
+    escritura: "empezar" | "cerrar" | "descartar";
+}
+/**
+ * Los reflejos que salen de pasar la cola de `antes` a `despues`, comparando por id. Solo las tareas CON ticket, y
+ * solo cuando su ESTADO cambió: guardar un aviso en `ticket` (que no cambia el estado) no vuelve a disparar nada. Una
+ * tarea nueva cuenta como «antes» ausente; una que desaparece (descartada) no escribe nada.
+ */
+export declare function reflejosPendientes(antes: readonly Tarea[], despues: readonly Tarea[]): ReflejoPendiente[];
+/**
+ * Si al EMPEZAR hay que mover el ticket: no si ya está en curso (una reanudación, o la persona lo movió a mano). Al
+ * cerrar se mueve siempre: comentar y pasar a PROBAR es lo que dice que está hecho.
+ */
+export declare function hayQueTransicionar(escritura: "empezar" | "cerrar", categoriaActual: CategoriaDeTarea): boolean;
+/** El `Vinculo` con el que se escribe en el ticket de una tarea: el COPIADO al crearla, nunca el del proyecto ahora. */
+export declare function vinculoDelTicket(ticket: TicketDeTarea): Vinculo;
+/**
+ * CERRAR un ticket: comentar y LUEGO transicionar. Una sola secuencia para el «Cerrar en …» de un chat y para una tarea
+ * en background que termina —dos copias acabarían distintas—:
+ *  - si `comentar` falla, LANZA y no se transiciona (no se dice «hecho» de algo sin explicar);
+ *  - si la transición falla, el comentario YA está en el gestor: no se lanza —repetir el cierre comentaría DOS veces—,
+ *    se devuelve el motivo en `falloDeTransicion` (traducido por quien llama, que sabe limpiar el mensaje remoto).
+ */
+export declare function cerrarTicket(g: Pick<GestorDeTareasPort, "comentar" | "transicionar">, v: Vinculo, clave: string, comentario: string, transicion: string | undefined, motivoDe: (error: unknown) => string): Promise<{
+    falloDeTransicion?: string;
+}>;
+/** Cada cuánto mira el gestor el proceso que ejecuta las tareas (la puerta 2). Más «Mirar ahora». */
+export declare const INTERVALO_DE_SONDEO_MS: number;
+/**
+ * El mapeo que se PROPONE para un flujo, por categoría: preparar = el primero «por hacer», lanzar = el primero «en
+ * curso», terminar = PROBAR si existe (el flujo de IXCODE) o el primero «terminada». La persona lo confirma o lo cambia.
+ */
+export declare function mapeoPropuesto(estados: readonly EstadoDelGestor[]): MapeoDeEstados;
+/**
+ * La transición que lleva un ticket al estado del MAPEO para ese momento (empezar → lanzar, cerrar → terminar), por el
+ * nombre de su destino sin mayúsculas. Sin estado mapeado, la regla de antes (`transicionPropuesta`). Con estado mapeado
+ * y sin transición que lleve a él, `undefined`: no se adivina otra.
+ */
+export declare function transicionHacia(ts: readonly TransicionDelGestor[], para: "empezar" | "cerrar", estados: MapeoDeEstados | undefined): TransicionDelGestor | undefined;
+/** Si un estado del gestor es el del mapeo (sin mayúsculas ni espacios de más). */
+export declare function esEstado(estado: string, mapeado: string | undefined): boolean;
+/**
+ * Lo que el sondeo tiene que hacer con un ticket. `lanzar` con `preparar` es la casilla «revisar el encargo» APAGADA:
+ * se amplía y se sube el encargo, y en la misma pasada se crea la tarea con él.
+ */
+export type AccionDelSondeo = {
+    tipo: "preparar";
+    ticket: TareaDelGestor;
+} | {
+    tipo: "lanzar";
+    ticket: TareaDelGestor;
+    preparar?: true;
+};
+/**
+ * Qué hacer en una pasada del sondeo, PURO: con los tickets ASIGNADOS a la cuenta del conector, el mapeo, qué tickets
+ * ya tienen encargo subido y cuáles ya tienen tarea (no descartada).
+ *  - En el estado de PREPARAR y sin encargo → preparar.
+ *  - En el estado de LANZAR y sin tarea → lanzar (con o sin encargo: sin él se usa el texto del ticket).
+ * Un ticket ya preparado no se vuelve a preparar; uno con tarea no lanza otra. Sin estado de lanzar no se lanza nada.
+ */
+export declare function accionesDelSondeo(o: {
+    tickets: readonly TareaDelGestor[];
+    estados: MapeoDeEstados;
+    conEncargo: ReadonlySet<string>;
+    conTarea: ReadonlySet<string>;
+    /** La casilla «revisar el encargo antes de lanzar». Apagada (lo de omisión): el de preparar se prepara Y se lanza. */
+    revisarEncargo?: boolean;
+}): AccionDelSondeo[];
+/** Si un comentario es un encargo subido por xonecode: empieza por la cabecera fija (con o sin negrita). */
+export declare function esComentarioDeEncargo(texto: string): boolean;
+/**
+ * El encargo que se ejecuta al LANZAR, leído de los comentarios del ticket: el ÚLTIMO con la cabecera, tal como esté
+ * (si la persona lo editó, su versión), sin la cabecera ni la firma; y lo comentado DEBAJO de él, como indicaciones
+ * añadidas. Sin encargo, `undefined` (se usará el texto del ticket).
+ */
+export declare function encargoDeLosComentarios(comentarios: readonly ComentarioDelGestor[]): {
+    encargo: string;
+    añadidos: string[];
+} | undefined;
+/** El encargo final de una tarea lanzada desde el gestor: el encargo, y debajo lo que se comentó después, dicho como tal. */
+export declare function encargoConAñadidos(encargo: string, añadidos: readonly string[]): string;
+/**
+ * A dónde va el ticket de una tarea DESCARTADA: al primer estado de la categoría «terminada» del flujo (en MAS, «Listo»;
+ * en KAN, «Finalizada»), decisión suya. Así sale de las pendientes y el sondeo no la vuelve a crear. No es el estado
+ * de «terminar» del mapeo: ese puede ser PROBAR, que diría que hay algo que probar.
+ */
+export declare function transicionDeDescarte(ts: readonly TransicionDelGestor[]): TransicionDelGestor | undefined;
+/** El comentario que deja en el ticket una tarea descartada. */
+export declare function comentarioDeDescarte(): string;
+/** La línea que encabeza el encargo de una tarea que vive en el gestor: el ticket, con su enlace si se conoce. */
+export declare function lineaDelTicket(nombreDelGestor: string, clave: string, url: string | undefined): string;
+/** El nombre para enseñar de un gestor, del catálogo de conectores («Jira»); uno que no está, por su id. */
+export declare function nombreDelGestor(conector: string): string;
+/** El encargo con la línea del ticket delante: así el agente y la conversación saben de qué ticket es y dónde está. */
+export declare function encargoConTicket(encargo: string, ticket: Pick<TicketDeTarea, "conector" | "clave" | "url">): string;

package/dist/core/textos.d.ts

@@ -0,0 +1,8 @@
+/**
+ * El título que se le pone a una conversación o a una tarea: su primera frase, entera.
+ *
+ * Vivía en `web/servidor/sesiones.ts` y se movió aquí cuando las TAREAS necesitaron el mismo
+ * título: `core/` no puede importar de `web/`, y una segunda copia habría divergido — con el
+ * síntoma de que la misma frase diera dos títulos distintos según quién la mirara.
+ */
+export declare function tituloDesde(texto: string): string;

package/dist/core/topeAgotado.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Lo que se le dice a quien delegó cuando a un especialista se le acabó el presupuesto.
+ *
+ * ## El fallo que cierra, medido el 19-09-2026
+ *
+ * Cada especialista corre con un tope de llamadas al modelo
+ * (`TOPE_DE_LLAMADAS_DEL_ESPECIALISTA`, con `exitBehavior: "end"`). Al agotarse, la librería
+ * añade un `AIMessage` con SU texto —«Model call limits exceeded: run level call limit reached
+ * with 15 model calls»— y salta al final. Y el `task` de deepagents devuelve **solo el último
+ * mensaje** (`extractLastMessage`).
+ *
+ * O sea que lo que el orquestador recibe como respuesta del especialista es esa frase, en
+ * inglés y en jerga del harness, **y todo lo que el especialista averiguó en sus quince
+ * llamadas se tira**. Medido: 100-160k de entrada por especialista, y menos de 900 tokens de
+ * salida devueltos. Por eso el orquestador encadena al siguiente: no es que enrute mal, es que
+ * no recibe nada con lo que seguir.
+ *
+ * **Por eso el tope es NUESTRO** (`topeDeLlamadas`) en vez de parchear el de la librería: sus
+ * dos ganchos de salida —el mensaje y el reset del contador— van detrás de un `jumpTo: "end"`
+ * que cortocircuita todo lo que haya debajo, así que **no corre NINGÚN middleware posterior**
+ * (medido contra la librería real, con `FakeToolCallingModel` y `runLimit: 0`). No había dónde
+ * engancharse: ni `afterAgent`, ni otro `beforeModel`. Reconocer su frase en inglés para
+ * sustituirla habría atado esto a un texto suyo, y encima sin sitio donde hacerlo.
+ *
+ * Esto NO sube el tope —que está medido y argumentado— ni lo quita. Hace tres cosas:
+ * devuelve el trabajo que se iba a tirar, lo marca como PARCIAL para que nadie lo lea como una
+ * conclusión, y dice qué hacer a continuación. Que un presupuesto se agote es normal; que se
+ * agote **en silencio** es el fallo.
+ *
+ * Puro y en `core/`: el texto se puede probar sin librería ni modelo. Quién lo mete en la
+ * conversación es de `agent/`.
+ */
+/**
+ * Cuánto del trabajo parcial se devuelve.
+ *
+ * Hay tope porque esto viaja como respuesta de una `task` y entra ENTERO en el contexto del
+ * orquestador: devolver sin límite convertiría el arreglo de un gasto en otro gasto. Lo que no
+ * cabe se dice, como en todas partes aquí.
+ */
+export declare const TOPE_DE_PARCIAL = 4000;
+export interface TopeAgotado {
+    /** El tope que se agotó, para que el mensaje no se invente la cifra. */
+    limite: number;
+    /** Lo último SUSTANCIAL que dijo el especialista, si dijo algo. */
+    parcial?: string;
+}
+/**
+ * El mensaje que sustituye al de la librería.
+ *
+ * **Habla con voz del harness y en primera persona del especialista**, porque quien lo va a
+ * leer es el orquestador y lo va a leer como la respuesta de aquél. Y dice las tres cosas que
+ * la frase de la librería no dice: que está a medias, qué había, y qué NO hacer — volver a
+ * encargarle lo mismo a otro es exactamente lo que se midió que pasa.
+ */
+export declare function mensajeDeTopeAgotado({ limite, parcial }: TopeAgotado): string;

package/dist/core/traerDeLaMaquina.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Cuánto se deja traer de una vez.
+ *
+ * El área de trabajo no es un almacén: lo que cae ahí se anuncia, se puede volver a leer y
+ * viaja con la sesión. Un tope es lo que impide que un `.mov` de 800 MB se copie tan callado
+ * como un `.png`. 64 MB deja pasar de sobra lo que esto resuelve —una maqueta, un zip de
+ * diseño, una captura— y corta lo que ya no es eso.
+ */
+export declare const TOPE_DE_TRAIDA: number;
+/**
+ * Por qué no se puede traer eso, o `undefined` si sí.
+ *
+ * **Lista BLANCA de forma**: tiene que ser una ruta absoluta de verdad. Una relativa no se
+ * resuelve contra nada fiable —el `cwd` de este proceso no es el proyecto— y aceptar `..`
+ * sería dejar que el destino lo eligiera quien escribe la ruta.
+ */
+export declare function motivoDeTraidaInaceptable(ruta: string): string | undefined;
+/**
+ * Con qué nombre queda dentro del área de trabajo.
+ *
+ * El último segmento y nada más. **Es lo que impide que el destino salga de la carpeta**: sin
+ * esto, un `/a/b/../../fuera.txt` escribiría fuera. Y de paso es lo que una persona reconoce
+ * en la lista de artefactos, que para eso está.
+ */
+export declare function nombreParaTraer(ruta: string): string;
+/**
+ * ¿Es esto una ruta de la MÁQUINA que alguien ha escrito como si fuera del proyecto?
+ *
+ * Solo se usa para poder CONTESTAR bien, nunca para abrir nada: quien abre es el montaje.
+ */
+export declare function esRutaDeMaquina(ruta: string): boolean;
+/** La misma ruta, ya en la forma que el agente puede abrir. */
+export declare function porQueNoSuelta(ruta: string): string;

package/dist/core/trazaDeErrores.d.ts

@@ -0,0 +1,83 @@
+/**
+ * El registro de lo que se traga un `catch`.
+ *
+ * **Por qué hace falta.** Este harness tiene 123 `catch` y casi todos callan a propósito: que
+ * no se pueda leer un adjunto, que falle el validador, que `git` no esté — ninguna de esas
+ * cosas puede tumbar un turno, y por eso se devuelven en vez de lanzarse. El precio es que
+ * cuando algo va mal **no queda rastro de nada**. Medido sobre una sesión que se colgó: el
+ * proceso estaba vivo y OCIOSO —`kevent`, sin un socket abierto, sin trabajo—, el `.jsonl`
+ * acababa en el mensaje de la persona sin su `fin`, y desde fuera no había forma de saber
+ * dónde se quedó. No es que el registro fuera pobre: es que no existía.
+ *
+ * **Es la misma pieza que `XONECODE_TRACE_TOOLS`** (`agent/turno/diagnosticoDeTools.ts`) y por
+ * la misma razón: apagado no cuesta nada, encendido deja un `.jsonl` que se puede leer después.
+ * Lo que cambia es qué anota — allí a dónde se fueron los tokens, aquí qué se calló.
+ *
+ * **Y el sumidero entra por PARÁMETRO**, como el de `core/bitacora.ts`: este módulo vive en
+ * `core/` y no toca disco, así que `npm test` no escribe nada y quien lo prueba ve lo que se
+ * anotó sin abrir un fichero.
+ */
+/**
+ * Un HITO: «empecé esto» / «lo acabé». No es un error, y es lo que de verdad encuentra un
+ * cuelgue.
+ *
+ * **Una excepción tragada no explica un proceso que se queda parado**, y eso se midió: el
+ * proceso colgado estaba OCIOSO —event loop en `kevent`, sin sockets, sin trabajo—, así que no
+ * había ninguna excepción que anotar. Lo que faltaba era saber qué fue lo último que EMPEZÓ y
+ * nunca terminó. Con pares `inicio`/`fin` eso se lee de un vistazo: el hito sin pareja es el
+ * sitio.
+ */
+export interface PasoAnotado {
+    donde: string;
+    fase: "inicio" | "fin";
+    /** Lo justo para distinguir dos pasos del mismo sitio. Nunca contenido ni rutas absolutas. */
+    detalle?: string;
+    /** Cuánto duró, solo en el `fin`. */
+    ms?: number;
+}
+/** Lo que se guarda de una excepción. Nunca el `stack`: ver `mensajeSeguro`. */
+export interface ErrorAnotado {
+    /** Dónde se tragó, en la forma `modulo#funcion`. Lo escribe quien llama, no se adivina. */
+    donde: string;
+    /** El `name` del error, que es lo que distingue un ENOENT de un fallo de parseo. */
+    nombre: string;
+    /** El `code` de un error de Node, cuando lo hay: es lo ÚNICO específico que se puede contar. */
+    codigo?: string;
+    /** El mensaje, ya sin rutas de la máquina. */
+    mensaje: string;
+}
+export declare function mensajeSeguro(mensaje: string): string;
+/** De un error, lo que se puede contar. */
+export declare function anotable(donde: string, error: unknown): ErrorAnotado;
+/** A dónde van los anotados. Uno solo por proceso: ver `anotarError`. */
+export type SumideroDeErrores = (anotado: ErrorAnotado | PasoAnotado) => void;
+/**
+ * Enchufa el sumidero. Sin esto, anotar no hace NADA — que es lo que debe pasar apagado.
+ *
+ * Es global a propósito, y es la única forma que funciona aquí: los sitios que se tragan una
+ * excepción están repartidos por todo el árbol —`core/`, `agent/`, `web/`— y muchos viven en
+ * funciones puras sin sitio donde inyectar nada. Pasarlo por parámetro habría obligado a
+ * cambiar la firma de medio harness para añadir una línea de diagnóstico, y eso es justo el
+ * cambio que nadie hace.
+ */
+export declare function ponerSumideroDeErrores(nuevo: SumideroDeErrores | undefined): void;
+/**
+ * Anota lo que un `catch` acaba de tragarse. **No cambia lo que pasa después.**
+ *
+ * Quien la llama sigue haciendo exactamente lo mismo que hacía: devolver `undefined`, seguir
+ * adelante, tragarse el fallo. Esto es un testigo, no una decisión — si además cambiara el
+ * control, cada sitio habría que volver a medirlo.
+ *
+ * Y NUNCA lanza: un registro de diagnóstico que rompe lo que observa es peor que no tenerlo.
+ */
+export declare function anotarError(donde: string, error: unknown): void;
+/**
+ * Anota que algo EMPIEZA, y devuelve la función que anota que acabó.
+ *
+ * Se usa envolviendo, no con dos llamadas sueltas: `const fin = anotarPaso(...); try { … }
+ * finally { fin(); }`. Así el `fin` no se puede olvidar en la rama del error, que es
+ * justamente la rama que interesa.
+ *
+ * Apagado no cuesta nada —ni una fecha— porque se sale antes de mirar el reloj.
+ */
+export declare function anotarPaso(donde: string, detalle?: string): () => void;

package/dist/core/tunel.d.ts

@@ -0,0 +1,45 @@
+/**
+ * El túnel de ngrok para la sesión remota: las reglas SIN efectos. Quien lanza el proceso es
+ * `agent/remoto/`; aquí solo se lee su log, se compone la dirección del puente y se dicen
+ * los fallos con texto FIJO nuestro.
+ *
+ * **Nada de lo que ngrok escribe cruza el cable.** Su salida lleva la ruta de la configuración,
+ * el correo de la cuenta y, en un error de autenticación, el authtoken tecleado: por eso el
+ * motivo de un fallo se decide por su CÓDIGO (`ERR_NGROK_xxx`) y lo que se enseña es una
+ * entrada de `MOTIVOS_DEL_TUNEL`, nunca la línea. Las líneas de los tests son salida real de
+ * ngrok v3 (`src/core/__oro__/ngrok-v3*.jsonl`), con la ruta, el correo y el token redactados.
+ */
+/** Texto fijo por causa. Es lo ÚNICO que sale de un fallo del túnel hacia el cable. */
+export declare const MOTIVOS_DEL_TUNEL: {
+    readonly noInstalado: "El componente de ngrok que trae xonecode no carga en esta máquina: reinstala xonecode.";
+    readonly autenticacion: "ngrok no acepta el authtoken (falta o no es válido).";
+    readonly dominio: "ngrok no deja usar ese dominio: no es de tu cuenta, o tu plan no admite dominios propios.";
+    readonly otraSesion: "Ya hay otro ngrok de tu cuenta abierto (en esta máquina o en otra): ciérralo y vuelve a encender.";
+    readonly sinDireccion: "ngrok no dio una dirección pública a tiempo.";
+    readonly seCerro: "ngrok se cerró.";
+    readonly paqueteViejo: "El paquete de la sesión remota instalado no trae el puente: actualízalo.";
+    readonly otro: "ngrok falló y no se pudo abrir el túnel.";
+    readonly puente: "No se pudo arrancar el puente local de la sesión remota.";
+    readonly authtokenSinForma: "Eso no tiene la forma de un authtoken de ngrok.";
+    readonly authtokenNoGuardado: "No se pudo guardar el authtoken.";
+};
+export type ClaveDeMotivoDelTunel = keyof typeof MOTIVOS_DEL_TUNEL;
+/** `https://host` → `wss://host/ws`: el puente de la sesión remota atiende el WebSocket en `/ws`. */
+export declare function servidorDeTunel(https: string): string;
+/** Un nombre de host con al menos un punto: sin esquema, ruta, puerto ni espacios. */
+export declare function motivoDeDominioInaceptable(dominio: unknown): string | undefined;
+/** Por qué se cerró ngrok, mirando solo el CÓDIGO `ERR_NGROK_xxx` de sus líneas, nunca su texto. */
+export declare function motivoDeSalidaDeNgrok(lineas: readonly string[]): "autenticacion" | "dominio" | "otraSesion" | "otro";
+/**
+ * Dónde guarda el authtoken el programa `ngrok`, por si ya lo usabas: el SDK no lee esa configuración, y sin mirarla
+ * habría que volver a pedirte el token. v3 por plataforma y la v2 de siempre (`~/.ngrok2`). Puro: la casa y el entorno
+ * entran por parámetro.
+ */
+export declare function rutasDeConfigDeNgrok(plataforma: string, entorno: Record<string, string | undefined>, casa: string): string[];
+/**
+ * El valor de una línea `authtoken:` no vacía, arriba (formato v2) o dentro de `agent:` (v3). `authtoken: ""` o sin
+ * valor no es una cuenta.
+ */
+export declare function authtokenDeConfig(texto: string): string | undefined;
+/** Lo que tiene un authtoken de ngrok: alfanumérico con `_`/`-`, sin espacios, empezando por letra o cifra. */
+export declare const FORMA_DE_AUTHTOKEN: RegExp;

package/dist/core/turno.d.ts

@@ -0,0 +1,154 @@
+import { Bitacora } from "./bitacora.js";
+import type { Artefacto, DomainEvent, Fase, OrigenDeLaTool, PendienteDeAprobacion } from "./events.js";
+import { type PropuestaDeTareas } from "./repartoDeEncargo.js";
+import type { VeredictoDelTurno } from "./actos.js";
+import type { DetalleDeLinea } from "./actos.js";
+/**
+ * La línea de una pregunta contestada sola en modo autónomo, para la piel que no pinta la tarjeta. Es el texto que
+ * salía antes como aviso, sin cambiar: stdio y la TUI siguen igual.
+ */
+export declare function textoDeConsultaAutonoma(c: {
+    pregunta: string;
+    elegida?: string;
+}): string;
+/**
+ * Lo que hace falta para pintar un turno. La implementan el renderizador de stdio y la TUI.
+ *
+ * `cerrarLinea` existe porque los tokens se escriben SIN salto —son la misma frase
+ * creciendo— y cualquier otra cosa que se pinte tiene que empezar en su propia línea. El
+ * motor lleva la cuenta de si hay una línea abierta; la piel decide qué significa cerrarla
+ * (en stdio es un `\n`, en la TUI es cerrar la burbuja del mensaje).
+ */
+export interface Piel {
+    token(texto: string): void;
+    cerrarLinea(): void;
+    /**
+     * El razonamiento del modelo, en trozos, como `token`. OPCIONAL: la piel que no lo
+     * implemente no lo verá, y la salida de stdio sigue siendo la de siempre —byte-idéntica
+     * por una tubería, que es lo que sostiene el e2e—. Hoy solo la web lo pinta.
+     */
+    razonamiento?(texto: string, origen?: OrigenDeLaTool): void;
+    /** El resumen de contexto, en trozos. OPCIONAL, por lo mismo que `razonamiento`. */
+    resumen?(texto: string): void;
+    /**
+     * Cualquier cosa que no sea un token. El segundo parámetro es OPCIONAL y solo lo manda el
+     * motor cuando la línea viene de una tool: dice cuál y si falló. Una piel que implemente
+     * `linea(texto)` con un solo parámetro lo ignora sin enterarse —así stdio y la TUI no
+     * cambian y la salida por una tubería sigue siendo byte-idéntica—, y la que quiera
+     * distinguir una lectura de una escritura ya no tiene que re-parsear la prosa de la línea.
+     *
+     * Sin detalle la línea NO es de una tool: por aquí pasan también el plan, las tareas y la
+     * verificación. Marcarlas como herramienta sería etiquetar mal un paso del motor.
+     */
+    linea(texto: string, detalle?: DetalleDeLinea): void;
+    pausa(pendientes: PendienteDeAprobacion[]): void;
+    fin(ms: number): void;
+    /**
+     * Alguien pidió LEER la memoria del proyecto (`core/memoria.ts`), con su origen si consta.
+     * OPCIONAL, como `fase?` y `razonamiento?`: stdio y la TUI no lo implementan —ahí ya se ve
+     * la línea de la tool— y la tubería sigue byte-idéntica.
+     *
+     * Es un método de la PIEL y no una cuenta de este motor porque el hecho es del TURNO y este
+     * motor se llama una vez por RONDA (aprobaciones, reparaciones): la piel es lo único que dura
+     * el turno entero, y quien lo estampa en su cierre.
+     *
+     * Dice que se PIDIÓ, no que se leyó: el evento `tool` sale cuando la tool se pide, y en
+     * TrueForge nunca trae su error. Una memoria que no existe da una lectura pedida igual.
+     */
+    memoriaPedida?(origen: OrigenDeLaTool | undefined): void;
+    /**
+     * El veredicto del verificador ENTERO, como dato. OPCIONAL, con la asimetría de `fase?`: la
+     * piel que lo implementa recibe el veredicto EN VEZ de las líneas —la web lo pinta con un
+     * botón por hallazgo, que de una línea de prosa no se puede sacar sin re-parsearla—, y la
+     * que no, sigue recibiendo las líneas de siempre, byte a byte.
+     */
+    verificacion?(veredicto: VeredictoDelTurno): void;
+    /**
+     * Si la piel sabe animar fases (el spinner del terminal), el motor le delega la fase
+     * y le dicta SOLO el texto — la decoración es cosa de la piel. Sin este método, la
+     * fase es una línea estática más.
+     */
+    fase?(texto: string, fase?: Fase): void;
+    /**
+     * Si la piel sabe reciclar avisos de sistema (el panel de notificaciones del
+     * terminal), el motor le delega los `aviso` — con la línea de tokens cerrada, como
+     * cualquier otra cosa que empieza su propia línea. Sin este método, el aviso es una
+     * línea estática más.
+     */
+    notificacion?(texto: string): void;
+    /**
+     * Si la piel sabe enseñar un artefacto —un diagrama, un panel—, el motor le da el dato
+     * entero en vez de solo la línea. OPCIONAL, como `razonamiento` y `fase`: la piel que no
+     * lo implemente se queda con la línea de siempre, así que stdio y la TUI no cambian y la
+     * salida por una tubería sigue siendo byte-idéntica. Hoy solo la web lo implementa.
+     *
+     * La línea se escribe SIEMPRE, la implemente o no: el artefacto no pasa por aprobación,
+     * así que la constancia de que se escribió no puede depender de qué piel esté delante.
+     */
+    artefacto?(artefacto: Artefacto): void;
+    /**
+     * El agente pregunta y el turno se para (`events.ts#consulta`). OPCIONAL, como `fase?`: la
+     * pregunta YA salió por `token`, así que quien no lo implemente —stdio, la TUI— la enseña
+     * igual, byte-idéntica. Hoy solo la web lo implementa, con un botón por opción.
+     */
+    consulta?(consulta: {
+        pregunta: string;
+        opciones: string[];
+    }): void;
+    /**
+     * Una pregunta que el harness contestó solo en modo autónomo (`events.ts#consulta-autonoma`). OPCIONAL: quien no lo
+     * implemente —stdio, la TUI— recibe el aviso de siempre (`textoDeConsultaAutonoma`), así que la salida por una
+     * tubería no cambia. Hoy solo la web lo implementa, con la tarjeta de la pregunta a la vista en el hilo.
+     */
+    consultaAutonoma?(consulta: {
+        pregunta: string;
+        opciones: string[];
+        elegida?: string;
+    }): void;
+    /**
+     * El agente propone repartir el encargo en tareas de fondo encadenadas (`events.ts#propuesta-de-tareas`). OPCIONAL:
+     * quien no lo implemente —stdio, la TUI— recibe una línea con las tareas numeradas; encolarlas solo se puede en la
+     * web, que es la que tiene la cola de tareas.
+     */
+    propuestaDeTareas?(propuesta: PropuestaDeTareas): void;
+}
+export interface OpcionesDelTurno {
+    /**
+     * Los avisos deterministas del final, calculados a partir de la bitácora.
+     *
+     * Es una función y no una lista porque las condiciones se evalúan CUANDO el turno
+     * termina, no cuando empieza: «¿ha corrido el verificador de pega en este turno?» solo
+     * se puede contestar al final. Y son CÓDIGO y no prompt porque a un modelo al que le
+     * pides que avise, a veces no avisa — y es justo el aviso que no puede faltar.
+     */
+    avisos?: (bitacora: Bitacora) => string[];
+    /**
+     * Si ESTA pasada cierra el turno: los avisos deterministas y `piel.fin()`.
+     *
+     * Existe porque un turno puede tener varias pasadas por `correrTurno` —una por ronda de
+     * aprobación, una por intento de reparación— y solo la última es el final. Antes cada
+     * pasada cerraba: stdio imprimía el tiempo una vez por ronda y el chat de la web plegaba
+     * el tramo una vez por ronda, medido. Es una función y no un booleano porque quien lo
+     * sabe es el flujo de eventos, y solo lo sabe al AGOTARSE — antes de eso no hay forma de
+     * decir si detrás viene otra pasada. Por omisión cierra, que es lo seguro: una pasada que
+     * revienta cierra igual, para que el tiempo y el aviso no se pierdan.
+     */
+    cerrar?: () => boolean;
+    /**
+     * Desde cuándo cuenta el tiempo del `fin`. Por omisión, desde que empezó ESTA pasada — que
+     * es lo correcto cuando el turno es una sola. Con varias pasadas y una sola que cierra,
+     * sin esto el `fin` diría solo lo que tardó la última: un turno de cuarenta segundos de
+     * trabajo, una aprobación y cinco de reanudación saldría como «5.0s». Quien encadena
+     * pasadas pasa aquí el `t0` del turno entero.
+     */
+    desde?: number;
+}
+/**
+ * Un turno completo: consume los eventos, cuenta lo que hay que contar, devuelve la
+ * bitácora.
+ *
+ * Nunca deja la línea de tokens abierta: el `finally` la cierra tanto si el turno termina
+ * bien como si el flujo revienta a mitad. Sin eso, el mensaje de error se pegaría al final
+ * de una respuesta a medio escribir.
+ */
+export declare function correrTurno(eventos: AsyncIterable<DomainEvent>, piel: Piel, opciones?: OpcionesDelTurno): Promise<Bitacora>;