xonecode 0.38.44 → 0.39.4

package/dist/agent/turno/turnoReal.d.ts

@@ -0,0 +1,210 @@
+import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
+import { type Decision } from "../../vendor/hitl.js";
+import { type MotorDeAgente } from "../../core/motor.js";
+import type { PendienteDeAprobacion } from "../../core/events.js";
+import type { LineaDeDiff } from "../../core/diff.js";
+import type { ConectoresPort, FuentesPort, IconosPort, ModelosPort, SkillsPort, VerifierPort } from "../../core/ports.js";
+import type { SesionReal } from "./sesionReal.js";
+import type { Entorno } from "../config/entorno.js";
+import { type CargarIndice } from "../navegacion/indiceEnDisco.js";
+import { type HechosDelTurno, type VeredictoDelTurno } from "../../core/juezDelTurno.js";
+/**
+ * Cierra las aprobaciones que se quedaron sin contestar cuando murió el proceso anterior.
+ *
+ * Solo existe desde que el hilo se guarda en disco (`agent/sesiones/checkpointer.ts`), y arregla un
+ * fallo MEDIDO —y medido dos veces, porque la primera medida estaba mal—. La forma del
+ * grafo importa: un grafo de un solo nodo donde `START` va al nodo interrumpido reejecuta
+ * ese nodo con el mensaje nuevo y vuelve a preguntar, que es inofensivo. El grafo del
+ * agente NO tiene esa forma: `START` va al MODELO, y el nodo parado es el de tools. Así que
+ * al reabrir una sesión que se cerró con una aprobación delante, lo que le llega al modelo
+ * es `human → ai(tool_calls) → human`: un `AIMessage` con llamadas a tool y ningún
+ * `ToolMessage` detrás. Gemini y OpenAI rechazan exactamente eso, así que el primer mensaje
+ * tras reabrir se iba en un 400 — y nada lo explicaba.
+ *
+ * El remedio es una respuesta SINTÉTICA por cada llamada colgada, diciendo la verdad: no se
+ * aplicó, porque la sesión se cerró antes de que nadie decidiera. Con eso el historial es
+ * válido y además honesto — el modelo se entera de que aquella escritura no llegó a pasar,
+ * en vez de dar por hecho que sí. Y es cierto: el `interrupt` pausa ANTES de escribir, o
+ * sea que el disco no se tocó.
+ *
+ * Se hace al ABRIR y no al empezar el turno porque es un arreglo del pasado, no del turno:
+ * dentro de una sesión viva las aprobaciones se resuelven por su camino normal. Un fallo
+ * aquí no puede impedir abrir la sesión, así que se traga — lo que se pierde entonces es
+ * este arreglo, no la conversación.
+ *
+ * Se exporta para poder probarla sin montar un grafo de verdad, igual que `decisionDeTool`.
+ */
+export declare function saldarAprobacionesHuerfanas(agente: unknown, hilo: string): Promise<void>;
+/**
+ * Abre una sesión real: agente, checkpointer, hilo y tracker se construyen UNA vez aquí, y
+ * viven en el cierre. Todo lo que sobreviva al primer turno tiene que salir de este cierre:
+ * reconstruir el agente fuera (o un `MemorySaver` nuevo por llamada) tiraría la conversación.
+ */
+export declare function abrirSesionReal(opciones: {
+    raiz: string;
+    modelos: ModelosPort;
+    skills: SkillsPort;
+    entorno: Entorno;
+    /** Para las aprobaciones. Sin él, una escritura pendiente termina el turno diciéndolo. */
+    pedirAprobacion?: (pendientes: PendienteDeAprobacion[], ficheros: Map<string, string>, diffs: Map<string, LineaDeDiff[]>) => Promise<Map<string, Decision>>;
+    /**
+     * El simulador, para verificar lo que el turno escribió. OPCIONAL, y su ausencia no se
+     * disimula: sin él, un turno que escribió termina con el aviso de que no se verificó y el
+     * motivo. Es un puerto por lo de siempre —`npm test` no puede necesitar el binario— y
+     * porque quien construye el turno no tiene por qué saber cómo se verifica.
+     */
+    verifier?: VerifierPort;
+    /**
+     * El `thread_id` del grafo. Entra por parámetro porque quien lo conoce es quien tiene
+     * IDENTIDAD para reanudar: en la web es el id de la sesión, y esa igualdad es lo que
+     * hace que reabrirla continúe el hilo en vez de releerlo. Sin él se genera uno, que es
+     * lo que hacía siempre.
+     *
+     * Antes había DOS ids para un mismo hilo —el de `EstadoDeSesion.hilo`, que es el que
+     * `/hilo` enseña, y el que se generaba aquí—, y solo coincidían después de un `/nuevo`.
+     */
+    hilo?: string;
+    /**
+     * Dónde se guarda la memoria del agente. Ausente = en memoria (`MemorySaver`), que es lo
+     * que hacía siempre y lo que sigue usando la consola de terminal: persistir un hilo que
+     * nadie puede volver a abrir solo engorda un fichero.
+     */
+    checkpointer?: BaseCheckpointSaver;
+    /**
+     * La carpeta donde caen los artefactos de esta sesión — lo que el agente ve como
+     * `/artefactos/`. Entra por parámetro porque quien sabe si hay sesión con identidad es
+     * quien la abrió: en la web es `.xonecode/sesiones/<id>/artefactos`, y sin sesión (la
+     * consola de terminal) se cae a `.xonecode/artefactos` del proyecto, que existe igual y
+     * no ensucia el índice con carpetas de hilos que nadie puede reabrir.
+     */
+    artefactos?: string;
+    /**
+     * El crítico visual, si esta ejecución tiene con qué preguntar.
+     *
+     * Entra por parámetro como `verifier`, así que `npm test` no le pregunta a ningún modelo, y
+     * su ausencia significa «esta ejecución no tiene crítico» y no «la pantalla está bien».
+     */
+    criticaVisual?: (captura: {
+        base64: string;
+        mime: string;
+    }, pantalla: string) => Promise<{
+        veredicto: string;
+        observaciones: string[];
+    }>;
+    /**
+     * El JUEZ del turno: ¿esto cumple lo que se pidió? Ausente = no se pregunta.
+     *
+     * Entra por puerto como el verificador y el crítico, y por lo mismo: llama a un modelo,
+     * así que `npm test` sigue sin necesitar clave. Lo puro —el prompt, el parser y qué hacer
+     * con cada veredicto— vive en `core/juezDelTurno.ts` y sí tiene test.
+     */
+    juezDelTurno?: (caso: {
+        objetivo: string;
+        respuesta: string;
+        hechos: HechosDelTurno;
+    }) => Promise<VeredictoDelTurno>;
+    /**
+     * La carpeta de los ADJUNTOS — lo que el agente ve como `/adjuntos/`, de solo lectura
+     * (`core/adjuntos.ts`). De una TAREA (`~/.xonecode/tareas/<id>/adjuntos/`) o, desde
+     * IXCODE-7, de una SESIÓN (`.xonecode/sesiones/<id>/adjuntos/`, los que una persona
+     * anexó en el CHAT): este campo no distingue el origen, es solo la ruta ya resuelta.
+     *
+     * Entra por parámetro y no se deduce, por lo mismo que `artefactos`: quien sabe qué
+     * carpeta corresponde es quien abrió la consola (`cli/main.ts#carpetaDeAdjuntosDelEjecutor`
+     * decide entre tarea y sesión), y aquí solo hay una raíz de proyecto. **Ausente en el
+     * terminal** (su hilo es un uuid nuevo por arranque, sin sesión que reabrir) **y en toda
+     * tarea sin adjuntos** — y entonces **el campo no se pone**, porque una cadena vacía
+     * montaría el cwd del proceso como si fueran los adjuntos de alguien.
+     */
+    adjuntos?: string;
+    /**
+     * ¿Las escrituras de ESTA sesión se aplican sin pedir aprobación?
+     *
+     * Es una FUNCIÓN y no un booleano porque se pregunta en cada ronda: el modo se cambia con
+     * `/aprobacion` sin cerrar la sesión, y un booleano capturado al abrir dejaría el cambio
+     * sin efecto hasta reabrir — justo en la dirección peligrosa la mitad de las veces.
+     *
+     * Quien decide es `core/modoDeEscritura.ts#seEscribeSinPreguntar`, y no este fichero: sus
+     * dos condiciones —el modo de la sesión y que haya alguien delante— dependen de quién
+     * montó la consola, y ninguna se puede comprobar aquí.
+     *
+     * **El MISMO predicado gobierna a los motores externos**, por el campo `modo` que este
+     * fichero le pasa a `opcionesDeSubagenteExterno`: sin eso valdría para la mitad de los
+     * agentes, y un modo que solo gobierna una mitad miente sobre lo que hace.
+     */
+    sinAprobacion?: () => boolean;
+    /** El raíz puede proponer tareas encadenadas (`proponer_tareas`). Solo TrueForge; ver `Consola.proponeTareas`. */
+    puedeProponerTareas?: boolean;
+    /** Una tarea de fondo: el agente decide sus dudas solo y resume al acabar. Solo TrueForge; ver `Consola.tareaDeFondo`. */
+    trabajoSinPersona?: boolean;
+    /**
+     * Cuántas RONDAS de aprobación admite un turno. Ausente = `MAX_APPROVAL_ROUNDS`, el de
+     * siempre.
+     *
+     * Existe porque el de la persona no vale para una tarea de fondo, y las dos mitades del
+     * argumento importan. `MAX_APPROVAL_ROUNDS` se dimensionó para alguien pulsando —«te lo
+     * he preguntado cinco veces, para»—; en una tarea autónoma una ronda no es una pregunta,
+     * es una TANDA de escrituras que se autorizan solas, y cinco tandas se agotan en un
+     * encargo mediano: medido, un turno se cortó con cuatro ficheros escritos y una escritura
+     * abandonada. Y quitarlo no vale, por el mismo argumento que el tope propio de los
+     * artefactos: cada pasada es una llamada al modelo y aquí no hay humano que frene el
+     * bucle.
+     *
+     * Gobierna los TRES sitios que miraban esa constante —el corte por rondas, el corte por
+     * tandas automáticas y la PREDICCIÓN de si la pasada cierra el turno—, y tiene que
+     * gobernar los tres: si la predicción divergiera del corte, un turno se quedaría sin
+     * `fin` o cerraría dos veces.
+     */
+    topeDeRondas?: number;
+    /**
+     * El cargador del índice de navegación. Ausente, se hace el de disco sobre `raiz`.
+     *
+     * Entra por parámetro por lo mismo que el verificador: toca disco y entra en la librería del
+     * linter, así que un test que no lo pueda doblar tendría que traerse un proyecto de verdad.
+     * Lo usan DOS —la tool del agente y la foto de hechos del turno— y es el mismo objeto a
+     * propósito: dos cargadores serían dos fuentes para la misma pregunta.
+     */
+    navegacion?: CargarIndice;
+    /**
+     * De dónde salen los iconos (IXCODE-18). Ausente = Iconify por la red, que es la composición de
+     * PRODUCCIÓN: un test que no la doble la tendría escrita pero no probada.
+     */
+    iconos?: IconosPort;
+    /**
+     * De dónde salen las fuentes. Ausente = Google Fonts por la red, la composición de PRODUCCIÓN,
+     * por lo mismo que `iconos`. Solo la usa TrueForge (deepagents es legacy y no se toca).
+     */
+    fuentes?: FuentesPort;
+    /**
+     * Los conectores MCP del proyecto, el MISMO servicio de Ajustes. Solo lo pasa la web (el único
+     * proceso que lo tiene); ausente, ningún agente recibe sus tools. Solo TrueForge los monta:
+     * deepagents es legacy.
+     */
+    conectores?: ConectoresPort;
+    /**
+     * El motor de agente (`core/motor.ts`). Ausente = el de la configuración: `XONECODE_MOTOR`, el
+     * `config.json` del proyecto o el global, y si no, `MOTOR_POR_OMISION`. La web lo pasa con el motor con
+     * el que NACIÓ la sesión; el terminal, `run`, el banco y los evals lo dejan a la configuración.
+     */
+    motor?: MotorDeAgente;
+    /**
+     * ¿Las dos trazas opt-in (tools y errores/hitos) van encendidas aunque nadie ponga una
+     * variable de entorno? Resuelto por quien LLAMA a partir de `Settings.depurar`
+     * (`core/settings.ts#depuracionActiva`) — este fichero no lee `settings.json`.
+     *
+     * **Ausente se comporta EXACTAMENTE como hoy** (`entornoConDepuracion(false, …)` devuelve el
+     * entorno intacto): así ningún test que no pase esto ve cambiar nada, y `npm test` sigue sin
+     * necesitar esto. Solo los arranques reales —CLI y consola web— resuelven la omisión de la
+     * fase de pruebas y la pasan aquí ya decidida.
+     */
+    depurar?: boolean;
+}): Promise<SesionReal>;
+/**
+ * Dónde caen los artefactos de una sesión: la carpeta que traiga quien la abre (la web, por sesión)
+ * o, sin ella —la consola de terminal, `run --real`—, `.xonecode/artefactos` del proyecto.
+ *
+ * **Una función para los DOS motores**, y es el arreglo: la caída vivía escrita dentro del camino
+ * de deepagents, y el de TrueForge pasaba la opción tal cual, o sea NADA cuando no venía. Sin
+ * carpeta no había montaje, y sin montaje `/artefactos/` era una ruta más del proyecto.
+ */
+export declare function carpetaDeArtefactosDeLaSesion(raiz: string, pedida: string | undefined): string;

package/dist/agent/turno/verificacion.d.ts

@@ -0,0 +1,85 @@
+import type { HallazgoDelTurno } from "../../core/events.js";
+import type { InformeVerificacion } from "../../core/ports.js";
+/**
+ * Los hallazgos, repartidos entre los ficheros que ESTE turno tocó y los demás.
+ *
+ * El simulador mira el proyecto entero —es su API—, y un error que ya estaba en un fichero que
+ * el agente no abrió no es del agente. Un hallazgo sin fichero no se puede atribuir: se enseña
+ * con los del turno, que es el lado conservador. Las rutas salen RELATIVAS: esto viaja al cable.
+ */
+export declare function repartirHallazgos(raiz: string, informe: InformeVerificacion, tocadosRelativos: readonly string[]): {
+    hallazgos: HallazgoDelTurno[];
+    preexistentes: number;
+    errores: number;
+};
+/**
+ * La huella de un veredicto rojo: sus ERRORES, no todos los hallazgos.
+ *
+ * Un aviso que va y viene no dice nada de si el error se está arreglando. Y se compara con la
+ * del veredicto anterior y no con «¿bajó el número?»: dos errores distintos en vez de dos
+ * iguales también es avance, y un modelo que arregla uno y rompe otro no debe quedarse
+ * bloqueado como si no hubiera hecho nada.
+ */
+export declare function huellaDeErrores(hallazgos: readonly HallazgoDelTurno[]): string;
+/** Lo que cuenta como fichero del PROYECTO para verificar: ni borrados ni `.xonecode/`. */
+export declare function cambiosQueSeVerifican<T extends {
+    ruta: string;
+    clase?: string;
+}>(cambios: readonly T[]): T[];
+/**
+ * Cuántas veces se le devuelven los hallazgos al agente para que los corrija. Dos: tres
+ * verificaciones en total. Un modelo que no arregla algo en dos intentos con el error
+ * delante no lo arregla al quinto, y cada intento son escrituras que pasan por aprobación
+ * humana — o sea, tiempo de una persona. La guarda de «no progresa» (misma huella dos
+ * veces) corta antes de llegar aquí cuando el modelo repite el mismo cambio.
+ */
+export declare const TOPE_REPARACIONES = 2;
+/**
+ * ¿Toca criticar la pantalla en esta pasada?
+ *
+ * PURA y exportada a propósito: la condición vivía dentro de `conVerificacion`, que es un
+ * cierre que TODOS los tests de este fichero doblan, y ahí una regla de producción se queda
+ * escrita y no probada — el patrón de fallo que este repo ha pagado nueve veces.
+ *
+ * Cuatro condiciones, y cada una dice algo distinto: sin crítico esta ejecución no puede
+ * preguntar (y eso NO es «la pantalla está bien»); sin capturas no hay nada que mirar; una vez
+ * por turno porque sus observaciones no son una huella y no hay forma de saber si una segunda
+ * vuelta avanza; y nunca por encima del tope de reparaciones, que es de todo el turno.
+ */
+export declare function tocaCriticarPantalla(estado: {
+    hayCritico: boolean;
+    capturas: number;
+    yaDisparo: boolean;
+    intento: number;
+}): boolean;
+/**
+ * El texto que se le devuelve al agente para que repare, de las DOS fuentes.
+ *
+ * Fuera del cierre por lo mismo que `tocaCriticarPantalla`. Y no se le dice CÓMO arreglarlo
+ * —eso lo sabe él o no lo sabe—, solo lo que se ha medido y lo único que importa aquí: que no
+ * invente nada para que el error desaparezca, que es justo lo que XOne no le reprocha.
+ */
+/**
+ * Lo que se le pide al agente cuando el verificador o el crítico ven algo.
+ *
+ * **Lleva el OBJETIVO delante, y ése es el arreglo.** Esta petición entra como
+ * `HumanMessage` en el mismo hilo (ver abajo), así que a partir de ese momento pasa a ser
+ * «el último humano» — y `conservarElEncargo` protege justo ése. O sea que sin el objetivo
+ * dentro, el encargo del usuario deja de estar protegido y lo sustituye la lista de
+ * hallazgos: el agente no se despista, le hemos cambiado el encargo por debajo y encima se
+ * lo recordamos en cada llamada.
+ *
+ * MEDIDO en un turno real: se pidió «tengo un error al ejecutar la app, arréglalo», se
+ * arregló (faltaba un `;` en `funciones.js`), y entonces el crítico visual vio tres textos
+ * recortados en otra pantalla —rotos desde antes, y sin relación con el arreglo—. El turno
+ * se fue a rediseñar el menú.
+ *
+ * **Y el objetivo es lo que decide si un hallazgo es trabajo o es ruido.** El mismo
+ * «BASICOS PLUS se corta» es ruido si el objetivo era arrancar la app, y es EL trabajo si
+ * el objetivo era arreglar los fallos visuales. Eso no lo dice el fichero que se tocó —el
+ * heurístico que se descartó— ni lo puede decidir el harness: lo decide el objetivo, y por
+ * eso viaja con la petición en vez de quedarse fuera.
+ */
+export declare function textoDeReparacion(hallazgos: readonly HallazgoDelTurno[], observaciones: readonly string[], 
+/** El encargo ORIGINAL de este turno. Ausente = no se pudo saber, y entonces no se afirma. */
+objetivo?: string): string;

package/dist/agent/turno/verificador.d.ts

@@ -0,0 +1,66 @@
+import type { InformeVerificacion, VerifierPort } from "../../core/ports.js";
+/** La forma que emite `xone-simulator validate --json` (xone-linter 1.4.0). */
+/**
+ * Cuando el simulador no pudo ni empezar. **Medido**: ante una ruta que no existe devuelve
+ * `{"success": false, "error": "No existe el directorio del proyecto: …"}` — sin `issues`,
+ * y **saliendo con código 0**, así que no lo caza ningún `catch` del proceso.
+ *
+ * Es un fallo del ENTORNO, no del proyecto, y por eso es una excepción y no un informe en
+ * rojo: un informe rojo dice «tu proyecto tiene errores», que aquí sería mentira.
+ */
+export declare class ErrorDelSimulador extends Error {
+}
+export interface SalidaDelSimulador {
+    success: boolean;
+    path?: string;
+    /** Presente SOLO en la forma de fallo, y entonces `issues` no viene. */
+    error?: string;
+    summary?: {
+        total: number;
+        errors: number;
+        warnings: number;
+    };
+    issues?: Array<{
+        severity: string;
+        code: string;
+        message: string;
+        file?: string;
+        location?: {
+            file: string;
+            line?: number;
+            column?: number;
+        };
+    }>;
+}
+/**
+ * De la salida del simulador al informe del harness. PURA: sin subprocesos.
+ *
+ * Separada de quien invoca el binario para poder probar la traducción con el fichero de
+ * `__oro__/` — es el patrón del puerto aplicado dentro del puerto, igual que el harness
+ * Python separa la función que recibe la sesión ya lista del puerto que la construye.
+ */
+export declare function aInforme(salida: SalidaDelSimulador): InformeVerificacion;
+/**
+ * El verificador real. NO lleva la marca `ES_DOBLE`: es de verdad, y `describe()` lo dirá.
+ *
+ * `validate` sale con código != 0 cuando encuentra errores, así que un fallo del proceso
+ * NO es un fallo del harness: es el resultado. Se distingue por si hubo JSON parseable —
+ * confundir las dos cosas es el patrón «fallo del proyecto != fallo del harness».
+ */
+export declare class SimuladorVerifier implements VerifierPort {
+    private readonly binario?;
+    /** Con un binario explícito se usa ESE, por el PATH; sin él, el de nuestra dependencia (`comoLanzarElSimulador`). */
+    constructor(binario?: string | undefined);
+    verificar(rutaProyecto: string): Promise<InformeVerificacion>;
+}
+/**
+ * Cómo se lanza `xone-simulator`: **el de NUESTRA dependencia** (`xone-linter`, cuyo `bin` es `dist/cli.js`), con el Node
+ * que corre xonecode; y solo si no se encuentra, `xone-simulator` por el PATH. Medido en la máquina Windows de un usuario
+ * (instalado con `npx`): el verificador lo llamaba por el PATH, donde no estaba, y cada turno cerraba con «no está
+ * instalado (ENOENT)» aunque el programa venía DENTRO del paquete. Aquí funcionaba porque estaba instalado global.
+ */
+export declare function comoLanzarElSimulador(resolver?: (id: string) => string): {
+    programa: string;
+    previos: string[];
+    nombre: string;
+};

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/acuseDeModelo.d.ts

@@ -0,0 +1,18 @@
+/**
+ * El acuse de `/modelo` — la frase tiene UN solo hogar.
+ *
+ * `consola.ts` la escribe y `tui/correrTui.ts` la re-parsea para actualizar la
+ * sidebar (el eco de `escribir` es la única costura que tienen los manejadores de
+ * consola para avisar de un cambio en caliente). Antes eran dos copias — el literal
+ * y un regex escrito a mano — sin nada que probara que decían lo mismo: si alguien
+ * retocaba la frase, la sidebar dejaba de enterarse sin que ningún test fallara.
+ * Escribir y leer viven aquí, y el test de ida y vuelta ata el par.
+ */
+import type { Papel } from "../core/ports.js";
+/** El acuse de un cambio de modelo: el papel ausente es «los tres papeles a la vez». */
+export declare function acuseDeModelo(papel: Papel | undefined, modelo: string): string;
+/** El acuse parseado: `{ modelo }` si cambiaron los tres, `{ papel, modelo }` si cambió uno. */
+export declare function modeloDeAcuse(texto: string): {
+    papel?: Papel;
+    modelo: string;
+} | undefined;

package/dist/cli/aprobar.d.ts

@@ -0,0 +1,162 @@
+import { REJECT_MESSAGE, MAX_APPROVAL_ROUNDS, type Decision } from "../vendor/hitl.js";
+import type { PendienteDeAprobacion } from "../core/events.js";
+import { type LineaDeDiff } from "../core/diff.js";
+import type { Escribir } from "./stdio.js";
+export { MAX_APPROVAL_ROUNDS, REJECT_MESSAGE, type Decision };
+/**
+ * Una línea del plan, CON lo que le pasa al fichero.
+ *
+ * `texto` es la línea entera tal como sale por el scrollback —signo y ruta, con sus dos
+ * espacios de sangría—: la tarjeta y el terminal enseñan lo MISMO porque es el mismo texto,
+ * y el día que alguien cambie el formato de uno tiene que cambiar el del otro.
+ *
+ * `cambio` es lo que el signo SIGNIFICA, y viaja aparte por la razón de siempre: `+` es
+ * sintaxis. Una piel que quisiera colorear lo que se añade leería el primer carácter de
+ * `texto`, y eso se rompe el día que la sangría cambie de ancho o que una ruta empiece por
+ * `-` —enseñando en verde un borrado—, sin un solo error. Es el MISMO dato que
+ * `CambioLocal.clase` (`core/planDeSubida.ts`), con los mismos tres valores.
+ *
+ * **Ausente = esta línea no habla de un fichero**: hoy solo pasa con la cabecera («SUBIDA A
+ * CLOUDSTUDIO — N operaciones»), que no es ni un añadido ni un borrado. Distinto de
+ * `"nuevo"`, que sí lo es.
+ */
+export interface LineaDelPlan {
+    texto: string;
+    cambio?: "nuevo" | "modificado" | "borrado";
+    /**
+     * La ruta del fichero de la línea, relativa al proyecto, como DATO: es lo que una piel
+     * necesita para pintar el plan como árbol y dejar elegir qué entra. Sacarla del `texto`
+     * sería leer sintaxis otra vez. Ausente en la cabecera, que no habla de un fichero.
+     */
+    ruta?: string;
+}
+/**
+ * Una pregunta cuya respuesta es SÍ o NO, con lo que se decide delante.
+ *
+ * Existe porque una piel rica no puede saber si el campo de texto sobra adivinándolo del
+ * enunciado: el `[s/N]` es SINTAXIS, y el día que alguien reescriba el prompt —o lo
+ * traduzca— la tarjeta que ofrece botones se quedaría con un editor, o al revés: dos
+ * botones sobre una pregunta de texto libre, que es el caso que no puede pasar y no daría
+ * ningún error. Aquí viaja la INTENCIÓN, que es lo mismo que ya hace `LineaDeConsola`
+ * diciendo si una línea es prosa.
+ *
+ * `lineas` es lo que se decide, línea a línea, tal como se enseña en el terminal: quien
+ * pregunta ya lo escribe con `escribir`, y una piel con tarjeta lo repite DENTRO de ella
+ * porque es el paso donde se DECIDE — la misma razón que hace viajar el diff entero en la
+ * aprobación de escrituras. No es contenido nuevo por el cable: son las mismas líneas que
+ * ese `escribir` ya manda.
+ *
+ * **Y el enunciado va SIN la pista de tecleo.** `politicaInteractiva` pregunta «¿Subir a
+ * CloudStudio?», no «¿Subir a CloudStudio? [s/N]»: el `[s/N]` es la pista de una piel que
+ * se contesta ESCRIBIENDO, y la pone esa piel (`PISTA_DE_DECISION`, ver abajo). Una tarjeta
+ * con dos botones no tiene nada que teclear, y llevarlo dentro del texto dejaba al cliente
+ * la opción de enseñarlo —donde se lee como «escribe s o n» delante de un botón— o de
+ * recortarlo a ciegas, que es leer sintaxis por la puerta de atrás.
+ *
+ * La respuesta sigue siendo una cadena por la misma puerta de siempre (`interpretAnswer`:
+ * `"s"` autoriza, cualquier otra cosa rechaza), y las dos caras de los botones son esas
+ * dos, no un vocabulario nuevo.
+ */
+export interface DecisionDeConsola {
+    lineas: readonly LineaDelPlan[];
+    /**
+     * `true` = quien contesta puede quedarse con PARTE de las líneas con `ruta` (la subida a
+     * CloudStudio en la consola web). Solo la honra una consola con `decidirConSeleccion`; las
+     * demás preguntan sí o no al plan entero, como siempre.
+     */
+    seleccionable?: true;
+    /**
+     * De QUÉ operación de sincronización es esta decisión, como dato: la web mantiene el diálogo
+     * abierto tras «Aceptar» hasta que llega el acto de ESA operación, y lo identifica por esto,
+     * no por el enunciado. Ausente = una decisión que no lanza ninguna operación.
+     */
+    operacion?: "subir" | "bajar";
+}
+/**
+ * La respuesta de una decisión que admite selección: la cadena de siempre
+ * (`interpretAnswer`) y, si la piel dejó elegir, las rutas que la persona dejó marcadas.
+ * `seleccion` AUSENTE es «no se eligió nada aparte»: el plan entero, como con `preguntar`.
+ */
+export interface RespuestaConSeleccion {
+    respuesta: string;
+    seleccion?: readonly string[];
+}
+/**
+ * La pista de una pregunta que se contesta TECLEANDO: `[s/N]`, con el defecto en
+ * mayúscula.
+ *
+ * La pone la piel que tiene un teclado delante —stdio y la TUI—, y solo esa: son las dos
+ * únicas que resuelven una pregunta con lo que alguien escriba. La consola web no la pone
+ * porque su tarjeta no tiene campo.
+ *
+ * Es SIEMPRE `[s/N]` y nunca `[S/n]` porque el Enter a secas NO aprueba una decisión: la
+ * asimetría de `CLAUDE.md` —aprobar ESCRIBE— y `politicaInteractiva` llama a
+ * `interpretAnswer` sin `interactive`, así que la cadena vacía rechaza aquí incluso con un
+ * TTY de verdad. La pista de la APROBACIÓN de escrituras sí alterna, y por eso la construye
+ * `pedirDecisiones` en el sitio donde se sabe si hay humano (`hayHumano()`): una pista no
+ * puede viajar con la pregunta cuando su contenido depende de la piel que la va a enseñar.
+ *
+ * **Límite declarado**: una decisión no puede cambiar su pista por pregunta. Hoy solo hay
+ * una que la use —la subida— y su defecto es fijo; el día que una decisión se apruebe con
+ * Enter, esto tiene que bajar al que la formula, como ya hace `aprobar.ts`.
+ */
+export declare const PISTA_DE_DECISION = " [s/N] ";
+/**
+ * Leer una línea. Entra por parámetro: sin esto, esto no se puede probar.
+ *
+ * El segundo parámetro es la FORMA de la respuesta, y es opcional a propósito: la mayoría
+ * de las preguntas —«número (Enter cancela)», una URL, una clave— son texto libre, y una
+ * implementación que no lo declare sigue valiendo (una función con menos parámetros es
+ * asignable), así que stdio, la TUI y los dobles de los tests no cambian de una línea.
+ */
+export type Preguntar = (pregunta: string, decision?: DecisionDeConsola) => Promise<string>;
+/**
+ * Pregunta por cada pendiente y devuelve las decisiones, en el mapa por id.
+ *
+ * **Fail-closed, y no es una preferencia: es la asimetría que protege el proyecto del
+ * usuario.** Aprobar ESCRIBE; rechazar no toca nada. Así que lo que no se entiende es
+ * RECHAZO, siempre. Y el Enter a secas solo aprueba con `interactive: true` —un TTY de
+ * verdad detrás—: en un pipe o en CI una línea en blanco no demuestra que haya nadie
+ * mirando, y esto aprueba escrituras sobre un proyecto real.
+ *
+ * `interpretAnswer` ya implementa las dos reglas y está medido: se reusa, no se reescribe.
+ *
+ * **`eof` existe porque un TTY no basta para saber que hay alguien.** `crearPreguntar`
+ * (`cli/stdio.ts`) devuelve cadena vacía por DOS motivos distintos que llegan idénticos:
+ * el usuario pulsó Enter, o la entrada se acabó (Ctrl-D, un stdin agotado a mitad de
+ * turno). Con `interactive: true` la cadena vacía APRUEBA —el Enter vale por un sí, y es
+ * un rasgo querido: quien lo pulsa tiene el diff delante—, así que sin distinguirlas un
+ * Ctrl-D aprobaba una escritura que nadie llegó a ver. Con `eof`, un readline cerrado
+ * degrada la pregunta a no-interactiva y ahí la cadena vacía ya rechaza. No se cambió
+ * `Preguntar` a `string | null`: contados a mano hay 18 sitios que llaman a un `preguntar`
+ * fuera de los tests, y en 16 la cadena vacía significa «cancela / usa el valor por
+ * omisión» —que es lo correcto también ante un EOF—. Solo las dos PUERTAS necesitan
+ * distinguir: esta y la subida a CloudStudio (`consola.ts#politicaInteractiva`, que lo
+ * resolvió de otra forma: allí el Enter no vale por un sí y el prompt es `[s/N]` siempre).
+ */
+export declare function pedirDecisiones(pendientes: PendienteDeAprobacion[], preguntar: Preguntar, escribir: Escribir, opciones?: {
+    interactive?: boolean;
+    /**
+     * ¿Se acabó la entrada? `crearDetectorDeEof` (`cli/stdio.ts`) es quien lo sabe para el
+     * readline de la consola; `eofDeStdin` (aquí abajo) para el stdin crudo del disparo
+     * único. Ausente = no se sabe, y entonces manda `interactive` a secas: los llamadores
+     * que no lo pasan se comportan exactamente igual que antes.
+     */
+    eof?: () => boolean;
+    fichero?: (id: string) => string | undefined;
+    /**
+     * Las líneas de diff del pendiente (ver `agent/turno/interrupts.ts` → `cambioDe`). Este es
+     * el ÚNICO sitio donde el contenido de una escritura se enseña, y es a propósito:
+     * aquí se DECIDE sobre ese contenido, y aprobar a ciegas es peor que no aprobar.
+     */
+    diff?: (id: string) => LineaDeDiff[] | undefined;
+}): Promise<Map<string, Decision>>;
+/**
+ * El EOF de stdin CRUDO, hermano de `crearDetectorDeEof` para quien no tiene un readline
+ * (el disparo único de `cli/run.ts`). `readableEnded` pasa a `true` al emitirse `end`
+ * — medido en este Node 22, junto con lo otro que hace falta saber aquí: un `on("end")`
+ * registrado DESPUÉS del EOF ya no dispara nunca.
+ */
+export declare function eofDeStdin(): boolean;
+/** El `preguntar` de producción: una línea de stdin. */
+export declare function preguntarPorStdin(): Preguntar;

package/dist/cli/config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `xonecode config` — diagnóstico de la configuración SIN llamar a ningún modelo.
+ *
+ * Un comando de diagnóstico no puede ser la vía por la que una clave acaba en un log o
+ * una captura, así que la regla dura de este fichero es: NUNCA se imprime ni un carácter
+ * de una credencial — ni truncada, ni los últimos cuatro. Solo «puesta»/«sin credencial»
+ * y de dónde sale. Por eso el JSON de salida se construye campo a campo a mano y jamás
+ * serializa el objeto `auth` de `cargar`, que SÍ lleva las claves en texto plano.
+ *
+ * Y al revés: un config MAL escrito no puede impedir que este comando funcione — es
+ * justo el que uno corre cuando la configuración está mal. Por eso siempre devuelve 0.
+ */
+import { type FuentesDeEleccion } from "../core/modelos.js";
+import { type Escribir } from "./stdio.js";
+export declare function cmdConfig(fuentes: FuentesDeEleccion, opciones?: {
+    json?: boolean;
+}, escribir?: Escribir, raiz?: string): number;