xonecode 0.38.44 → 0.39.4

package/dist/core/puedeLanzarse.d.ts

@@ -0,0 +1,181 @@
+/**
+ * El veredicto de «¿se puede lanzar esta app en este dispositivo?»: el predicado de listo y el
+ * catálogo de causas por las que NO lo está, cada una con su frase y con dónde se arregla.
+ *
+ * **Por qué esto existe, y es un caso medido.** El `launchApplication` del framework contesta
+ * `{"result":true}` y eso es un ACUSE, no una medida: a un proyecto cuyo `app.xml` declara
+ * `<connection name="main" connstring="bd/gestion.db" />` y que **no tiene** ese fichero le
+ * contestó `true`, y la app murió detrás en un diálogo «Error opening database». El verificador
+ * no lo caza —`xone-simulator validate` sobre ese mismo proyecto da `success: true`, 0 errores
+ * y 0 avisos, porque **no mira la conexión**—, así que el síntoma es el peor de todos: nada
+ * falla por ningún lado y la app no arranca.
+ *
+ * **Y lo que se comprueba NO se deduce de `app.xml`: la base es `bd/gestion.db` POR DEFECTO.**
+ * Aquí hubo una regla que solo miraba los `connstring` declarados con forma de ruta, y es un
+ * **falso negativo**, que es el error peligroso de este módulo: medido sobre los proyectos
+ * reales, **solo MinitsMT declara su base** (`<connection name="NoReplica"
+ * connstring="bd/gestion.db" />`); MyAllXOne y Replanteos_2026 declaran únicamente conexiones de
+ * proveedor (`Provider=…`), AppDemo no declara **ninguna**, y **los cuatro tienen su
+ * `bd/gestion.db`**. O sea: la declaración es la forma RARA, y una regla que dependiera de ella
+ * dejaría sin comprobar justo lo que se quería comprobar —el caso medido, el diálogo «Database
+ * not found»— en tres de cada cuatro proyectos. Comprobado en el aparato: XOne usa esa ruta por
+ * defecto, se declare o no. Así que la comprobación tiene DOS entradas y una sola pregunta: la
+ * ruta de la convención siempre, más cualquier otra ruta que el `app.xml` declare —una segunda
+ * base es un sitio distinto donde puede faltar un fichero—.
+ *
+ * Datos puros y sin efectos: lo caro entra por parámetro (`existe`, los textos de los ficheros),
+ * que es lo que deja `npm test` sin disco y sin dispositivo. Quien lee el proyecto y mide la
+ * máquina es `web/servidor` / `agent/`.
+ *
+ * **Y el catálogo es una unión discriminada y no una lista de booleanos.** Cada causa lleva sus
+ * datos (el nombre del dispositivo, el `connstring` que falta) porque la frase los necesita, y
+ * el `switch` de `motivoDeBloqueo` va exhaustivo y sin `default`: añadir una causa es un error de
+ * compilación hasta que alguien escriba qué decir y dónde se arregla. Una lista de booleanos se
+ * amplía en silencio, y lo que se amplía en silencio es lo que acaba sin frase.
+ */
+import { type Dispositivo } from "./dispositivos.js";
+import { type ConexionDeclarada } from "./descriptoresDeApp.js";
+/**
+ * Lo MÍNIMO que el veredicto necesita saber del framework de XOne en el dispositivo.
+ *
+ * **Se declara aquí y no se importa de `agent/dispositivos/dispositivosEnMaquina.ts`**, que tiene el tipo
+ * rico (`FrameworkEnDispositivo`, con `paquete` y `detalle`) y que lo satisface por ESTRUCTURA:
+ * `core/` declara la forma que consume y no mira hacia `agent/`, que además importa de `core/`
+ * y sería un ciclo. Y no lo caza ningún test —`core/imports.test.ts` vigila langchain, ink y
+ * compañía, no esto—, así que el día que alguien «reutilice» el tipo de `agent/` no habrá rojo
+ * que leer: habrá una capa mirando hacia arriba en silencio.
+ */
+export interface FrameworkMedido {
+    instalado: boolean;
+}
+/**
+ * La base local de una app XOne, siempre en el mismo sitio: `bd/gestion.db`.
+ *
+ * **Es una convención de la plataforma, no algo que haya que leer de `app.xml`.** XOne la usa
+ * por defecto cuando no se declara ninguna conexión, así que un proyecto que no la declara **sí
+ * la necesita**, y comprobar solo lo declarado dejaría sin comprobar el caso más común —está
+ * medido: de cuatro proyectos reales, tres no la declaran y los cuatro la tienen—.
+ *
+ * Se comprueba tal cual, sin normalizar, porque es como la nombra el propio XOne y como la
+ * declara el esqueleto de `core/esqueleto.ts`.
+ */
+export declare const RUTA_DE_LA_BASE = "bd/gestion.db";
+/**
+ * Todo lo que puede impedir un lanzamiento, con el dato que hace falta para decirlo.
+ *
+ * Las tres primeras son del eje DISPOSITIVO (no hay ninguno, el elegido ya no está, o está pero
+ * no se llega a él), `plataforma-sin-camino` es del eje CAMINO, las dos del framework son del
+ * eje MEDIDA, y las cuatro últimas del PROYECTO —de `app.xml` para abajo—.
+ *
+ * **Y no está «no declara ninguna conexión», que estuvo y se quitó.** Un proyecto que no declara
+ * ninguna `<connection>` no tiene nada que comprobar, y no declarar ninguna no es síntoma de
+ * nada: medido, AppDemo —la app con la que se prueba— declara cero y arranca. Bloquear ahí es el
+ * mismo error que este catálogo evita para los `connstring` de proveedor, cometido con el caso
+ * vecino, y además negaría el lanzamiento de la app que alguien nombró. Lo que el recorrido
+ * quiera decir de las conexiones lo lleva `Veredicto.conexiones`, que es un DATO y no una causa.
+ */
+export type CausaDeBloqueo = {
+    causa: "sin-dispositivo-elegido";
+} | {
+    causa: "dispositivo-desconocido";
+} | {
+    causa: "dispositivo-no-alcanzable";
+    nombre: string;
+    estado: Dispositivo["estado"];
+} | {
+    causa: "framework-ausente";
+    nombre: string;
+} | {
+    causa: "framework-no-medido";
+    nombre: string;
+} | {
+    causa: "sin-app-xml";
+} | {
+    causa: "app-xml-ilegible";
+    motivo: string;
+} | {
+    causa: "falta-el-fichero-de-la-conexion";
+    connstring: string;
+} | {
+    causa: "falta-la-base";
+} | {
+    causa: "plataforma-sin-camino";
+    plataforma: Dispositivo["plataforma"];
+};
+/**
+ * Lo que el veredicto necesita, ya resuelto por quien SÍ puede tocar el disco y la máquina.
+ *
+ * El dispositivo llega resuelto porque resolverlo es cruzar la elección de la sesión con la
+ * última medida, y eso pide el informe entero: aquí llega el `Dispositivo` o nada.
+ */
+export interface EntradaDeVeredicto {
+    /** El dispositivo de la sesión, ya cruzado con la última medida. `undefined` = no hay ninguno. */
+    dispositivo: Dispositivo | undefined;
+    /**
+     * El id que la sesión tiene ELEGIDO, cuando no se ha podido resolver contra la medida.
+     *
+     * Es lo único que separa «no has elegido nada» de «elegiste uno que ahora no está»: las dos
+     * llegan aquí con `dispositivo: undefined`, y sin este campo la segunda se contaría como la
+     * primera — decirle a alguien que no eligió cuando sí eligió es la clase de mentira que esta
+     * casa no se permite. Con el elegido resuelto se deja sin poner: manda `dispositivo`.
+     */
+    elegido?: string;
+    /** Lo que se midió del framework en ESE dispositivo. `undefined` = nadie lo ha medido. */
+    framework: FrameworkMedido | undefined;
+    /** El texto de `app.xml` del proyecto. */
+    xml: string | undefined;
+    /**
+     * Por qué no se pudo leer `app.xml`: UNA línea, nunca la salida entera. Que venga puesto es
+     * lo que distingue «no hay app.xml» de «hay algo que no se deja leer», que no son la misma
+     * cosa ni se arreglan en el mismo sitio.
+     */
+    motivoDeLectura?: string;
+    /** El texto de `app.ini`. **Su ausencia NO bloquea**: sin él solo se pierde el nombre. */
+    ini: string | undefined;
+    /** ¿Existe esa ruta del proyecto? Inyectado: `core/` no toca el disco. */
+    existe: (rutaRelativa: string) => boolean;
+}
+export interface Veredicto {
+    listo: boolean;
+    /** TODAS las causas, no solo la primera. Ver `motivoDeBloqueo` para la frase de cada una. */
+    causas: CausaDeBloqueo[];
+    /** El nombre de la app que dice `app.ini`, si se pudo leer. Ausente = no consta. */
+    app?: string;
+    /** Las conexiones declaradas, para poder decirlas en el recorrido antes de lanzar. */
+    conexiones: ConexionDeclarada[];
+}
+/**
+ * ¿Está este dispositivo listo para lanzar? Alcanzable **y** con el framework instalado.
+ *
+ * **Un framework sin medir NO es un framework ausente, y aquí las dos cosas dan «no listo» pero
+ * la frase que lo acompaña es distinta** —«no se sabe» no se arregla instalando nada—. El
+ * predicado se queda con el lado conservador: un botón de lanzar sobre un «no se sabe» es la
+ * promesa que este repo no se permite, porque el acuse del framework llega igual y el fallo
+ * aparece detrás, en la app.
+ *
+ * Es el eje DISPOSITIVO de `puedeLanzarse`, no el veredicto entero: un proyecto sin `app.xml`
+ * bloquea aunque esto diga que sí. `puedeLanzarse` no lo recalcula por su cuenta —el veredicto
+ * sale de su lista de causas, que es exhaustiva sobre este eje— y hay un test que ata las dos
+ * respuestas para que no puedan divergir.
+ */
+export declare function dispositivoListo(dispositivo: Dispositivo | undefined, framework: FrameworkMedido | undefined): boolean;
+/**
+ * El veredicto entero: el dispositivo, el camino, la medida del framework y el proyecto.
+ *
+ * **El orden de las causas es el de la lectura**, y no es alfabético a propósito: primero lo que
+ * hay que arreglar antes de que nada más importe —elegir un dispositivo— y al final el proyecto,
+ * para que quien esté mirando la pantalla no arregle una cosa y descubra la siguiente después.
+ * Las causas son todas las que hay, no la primera.
+ */
+export declare function puedeLanzarse(entrada: EntradaDeVeredicto): Veredicto;
+/**
+ * UNA frase por causa, en español, y **cada una dice DÓNDE se arregla**.
+ *
+ * El `switch` va exhaustivo y sin `default` a propósito: un `default` que devolviera «no se
+ * puede» taparía la causa nueva en vez de obligar a escribir qué falta y con qué se arregla, que
+ * es justo lo único que esta pestaña tiene que decir. Y por eso ninguna frase es un «no se
+ * puede» a secas: quien la lee está mirando una pantalla que le acaba de negar algo, y lo único
+ * que puede hacer con un «no se puede» es irse a buscar por su cuenta —o creer que xonecode
+ * tenía que haberlo puesto él.
+ */
+export declare function motivoDeBloqueo(causa: CausaDeBloqueo): string;

package/dist/core/puertosDeAvd.d.ts

@@ -0,0 +1,59 @@
+/**
+ * El puerto LOCAL del túnel de hotswap, uno por AVD.
+ *
+ * Medido: `adb -s B forward tcp:8443 tcp:8443` le QUITA el puerto a `A` sin error, así que
+ * con dos emuladores y un puerto fijo la sesión de uno acaba hablando con el aparato del otro.
+ * Dentro de cada aparato el 8443 es independiente; lo que se reparte es el del Mac.
+ *
+ * Con UN solo AVD el puerto es el de siempre y no hay nada que decidir (decisión suya: la UI
+ * no enseña campo). Pero se GUARDA igual (`asignarPuertosPendientes` también siembra al único):
+ * si se sembrara solo al aparecer el segundo, por orden alfabético, un AVD nuevo que ordenara
+ * antes le quitaría el 8443 al que ya se usaba.
+ *
+ * **Un móvil FÍSICO también tiene el suyo, por su serie** (IXCODE-32): iba siempre al 8443, que
+ * es también el del primer AVD, y con el móvil y el emulador enchufados el último `adb forward`
+ * se quedaba el puerto — la sesión del móvil acababa hablando con el emulador sin error. Se
+ * siembra igual que el de un AVD (solo AÑADE) y, mientras no está sembrado, es el primero LIBRE
+ * (`primerPuertoLibre`), el mismo que la siembra le daría.
+ *
+ * Puro: ni disco ni red. La copia que LEEN los scripts está en
+ * `skills/xone-hotswap/lib/dispositivo.mjs`, y un test compara las dos.
+ */
+import type { AjustesDeDispositivos } from "./settings.js";
+/** El puerto del servidor hotswap DENTRO del aparato, y el local por omisión. */
+export declare const PUERTO_DEL_HOTSWAP = 8443;
+/** La MISMA forma que acepta `arranqueDeEmulador.ts`: lo que puede ser una carpeta de `~/.android/avd`. */
+export declare const FORMA_DE_NOMBRE_DE_AVD: RegExp;
+/** La forma de un serial de adb: USB (`R58M123`), por red (`192.168.1.5:5555`) o mDNS (`adb-…._adb-tls-connect._tcp`). */
+export declare const FORMA_DE_SERIE: RegExp;
+export declare function puertoDeAvd(ajustes: AjustesDeDispositivos | undefined, avd: string): number;
+/** El puerto de un móvil físico: el guardado para su serie o, sin él, el primero libre. */
+export declare function puertoDeFisico(ajustes: AjustesDeDispositivos | undefined, serie: string): number;
+/**
+ * El puerto local del túnel de un Android, sea emulador o físico. Un emulador cuyo AVD no se pudo
+ * identificar va al de siempre, como hasta ahora: no hay de quién leer otro.
+ */
+export declare function puertoDeDispositivo(ajustes: AjustesDeDispositivos | undefined, d: {
+    id: string;
+    clase: "emulador" | "simulador" | "fisico";
+    avd?: string;
+}): number;
+/**
+ * Los puertos que faltan, o `undefined` si no falta ninguno. Solo AÑADE: un puerto guardado no
+ * se mueve nunca. Entre los que faltan, por orden alfabético (que no dependa del orden de
+ * `emulator -list-avds`), desde el 8443 si está libre. Como el único AVD ya queda sembrado, el
+ * orden solo decide entre AVD que aparecieron a la vez.
+ */
+export declare function asignarPuertosPendientes(avds: readonly string[], ajustes: AjustesDeDispositivos | undefined): Record<string, number> | undefined;
+/**
+ * Lo mismo para los móviles físicos Android medidos, por su serie: solo AÑADE, y salta todo
+ * puerto guardado (de AVD o de otro físico). Se llama DESPUÉS de sembrar los AVD, con los ajustes
+ * ya releídos, para que un AVD nuevo y un físico nuevo no se lleven el mismo.
+ */
+export declare function asignarPuertosDeFisicos(series: readonly string[], ajustes: AjustesDeDispositivos | undefined): Record<string, number> | undefined;
+export declare function motivoDePuertoInaceptable(puerto: number, avd: string, ajustes: AjustesDeDispositivos | undefined): string | undefined;
+export declare function motivoDeNombreDeAvdInaceptable(nombre: string, existentes: readonly string[]): string | undefined;
+/** Los argumentos de `emulator`. Sin ventana lleva `-no-metrics`: su aviso será una pregunta que nadie ve. */
+export declare function argsDeArranque(avd: string, opciones: {
+    sinVentana?: boolean;
+}): string[];

package/dist/core/recargaEnCaliente.d.ts

@@ -0,0 +1,52 @@
+export type ClaseDeRecarga = "coleccion" | "js" | "css" | "relanzar" | "no-aplica";
+/**
+ * Cómo se aplica `ruta` (relativa, con `/`) con estos `bytes`. El texto se mira byte a byte: la
+ * etiqueta `<coll` es ASCII en cualquier tabla.
+ */
+export declare function claseDeRecarga(ruta: string, bytes: Uint8Array): ClaseDeRecarga;
+/**
+ * El nombre de la codificación que se le dice al framework para que lea ESTOS bytes. Es la misma
+ * regla que la lectura del agente y del editor (`core/codificacion.ts`): UTF-8 si lo es; si no, la
+ * tabla de 8 bits que declare el prólogo (ISO-8859-15) o windows-1252. Mandar `UTF-8` a secas
+ * —lo que hace el script— enseñaba en el aparato un «�» en cada tilde de un `.xne` Latin-1.
+ * Los nombres son los de `java.nio.charset`, que es quien los lee al otro lado.
+ */
+export declare function codificacionParaElAparato(bytes: Uint8Array): "UTF-8" | "ISO-8859-15" | "windows-1252";
+/**
+ * Lo que se le da a `loadCollection`: el MISMO XML, en UTF-8 y con el prólogo diciendo UTF-8.
+ *
+ * MEDIDO en el emulador (framework 5.0.5.5dev) con un `.xne` en ISO-8859-15 y «Año ñá»: con sus
+ * bytes y `encoding: "ISO-8859-15"` el aparato pintaba «Año ñá» —y estropeaba también el
+ * «Contraseña» que ya estaba—; con el texto en UTF-8 y el prólogo cambiado a UTF-8 se ve bien. El
+ * framework decodifica con `encoding` y su analizador vuelve a leer el prólogo: si los dos no dicen
+ * lo mismo que los bytes, cada tilde sale doble. Solo para la copia EN MEMORIA: lo que se sube a
+ * disco (`uploadFile`) son los bytes tal cual, que es lo que el framework lee al relanzar.
+ */
+export declare function xmlParaCargarEnMemoria(bytes: Uint8Array): Uint8Array;
+/** Dónde guarda el framework lo que se le sube: `app_<nombre en minúsculas>/<ruta>` (medido). */
+export declare function destinoEnElAparato(app: string, ruta: string): string;
+/**
+ * En qué acabó una recarga. Cada estado es un hecho distinto y se pinta distinto:
+ * - `aplicada`: subido, aplicado, y la app CONTESTA su árbol después (no «cambiado»: `result:true`
+ *   es «aceptado», y lo que se cambió lo comprueba quien mira la pantalla).
+ * - `relanzar`: subido; para verse hay que relanzar la app, y eso se ofrece, no se hace.
+ * - `relanzada`: se relanzó a petición y la app volvió a contestar.
+ * - `sin-app`: no hay a dónde recargar —la app no contesta, o no hay aparato, o no está en la medida—;
+ *   `motivo` dice cuál. No se tocó nada.
+ * - `desplegando`: se pidió PROBAR y la app no corría, así que se lanzó el despliegue entero (el de
+ *   Ejecutar); su recorrido se cuenta allí.
+ * - `desplegada`: el despliegue que lanzó «Probar» acabó con la app viva.
+ * - `ocupado`: hay un despliegue en curso; no se recarga encima de él.
+ * - `no-aplica`: este fichero no se lleva suelto.
+ * - `fallo`: algo dijo que no; `motivo` es la frase literal.
+ */
+export type EstadoDeRecarga = "aplicada" | "relanzar" | "relanzada" | "sin-app" | "desplegando" | "desplegada" | "ocupado" | "no-aplica" | "fallo";
+export interface ResultadoDeRecarga {
+    estado: EstadoDeRecarga;
+    /** Qué se hizo, cuando se hizo algo: la clase con que se aplicó. */
+    clase?: ClaseDeRecarga;
+    /** UNA línea: lo que dijo el framework, o por qué no hay a dónde recargar. En `fallo` y `sin-app`. */
+    motivo?: string;
+}
+/** La frase que enseña la cabecera del editor. Pura para que el test la fije. */
+export declare function textoDeRecarga(r: ResultadoDeRecarga): string;

package/dist/core/referenciasDeImagen.d.ts

@@ -0,0 +1,36 @@
+/**
+ * De dónde puede salir la MAQUETA con la que se compara una captura (IXCODE-18).
+ *
+ * ## Por qué existe, medido
+ *
+ * Las tools de comparación (`comparar_capturas`, `xone_critica_visual`) solo leían de
+ * `/artefactos/`. Pero la maqueta de un encargo no vive ahí: la trae la persona en el CHAT
+ * (`/adjuntos/`) o está en el proyecto (`/diseno/`). Rehaciendo una calculadora de Stitch desde cero,
+ * el agente lo dijo tal cual —«el proyecto no traía maqueta»— y el crítico corrió sin referencia:
+ * su verde significaba «nada roto», y no vio que faltaba la barra superior entera ni que el teclado
+ * no llegaba abajo. Comparar contra el diseño era imposible por una ruta, no por falta de tool.
+ *
+ * ## Qué se acepta
+ *
+ * Una imagen PNG o JPEG en uno de tres sitios, por su ruta VIRTUAL:
+ * - `/artefactos/…`: lo de siempre.
+ * - `/adjuntos/…`: lo que la persona adjuntó (de solo lectura).
+ * - Un fichero del PROYECTO (`/diseno/screen.png`): cualquier ruta cuyos segmentos sean llanos.
+ *
+ * **Lista BLANCA de forma, sobre el TEXTO** (como `esRutaDeArtefacto`): letras, cifras, punto, guion y
+ * guion bajo; nada de `..`, `.`, segmentos vacíos, barra invertida, NUL. Y en el proyecto **ningún
+ * segmento puede empezar por punto**: eso deja fuera `.env`, `.git` y `.xonecode` (la memoria, los
+ * planes y `checkpoint.sqlite`) sin depender de una lista de nombres que se quede corta. Lo que
+ * compruebe la lectura real (`agent/grafo/lectorDeReferencias.ts`) es lo mismo, dos veces: texto y
+ * `realpath`.
+ */
+export type OrigenDeImagen = "artefactos" | "adjuntos" | "proyecto";
+export interface ImagenReferida {
+    origen: OrigenDeImagen;
+    /** La ruta detrás de la carpeta de su origen (para el proyecto, sin la barra inicial). */
+    relativa: string;
+    /** El último segmento: lo que se le enseña a una persona. */
+    nombre: string;
+}
+/** La imagen a la que apunta la ruta, o el MOTIVO en palabras. Comprueba el texto y no abre nada. */
+export declare function imagenReferida(ruta: string): ImagenReferida | string;

package/dist/core/remoto.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Qué cruza el puente de la sesión remota, en las dos direcciones. Es la FRONTERA de seguridad
+ * del lado de xonecode: lo que no está aquí no sale de la máquina ni entra en la consola, aunque
+ * el móvil lo pida. Puro y sin dependencias (`core/`); el paquete del puente (`xonecode-remoto`) tiene
+ * su propia validación para la web, pero quien decide aquí es xonecode.
+ */
+export type EntradaDelMovil = {
+    clase: "prosa";
+    texto: string;
+    detener?: true;
+} | {
+    clase: "decision";
+    decisiones: Record<string, "approve" | "reject">;
+    consola?: string;
+} | {
+    clase: "respuesta";
+    texto: string;
+} | {
+    clase: "feedback";
+    tarea: string;
+    texto: string;
+} | {
+    clase: "continuar";
+    tarea: string;
+} | {
+    clase: "cancelar";
+}
+/** Ver un artefacto del hilo (una captura): su ruta VIRTUAL, la del acto `artefacto`. Quien lo
+ *  sirve vuelve a pasarla por `esRutaDeArtefacto` y el lector la comprueba contra el disco. */
+ | {
+    clase: "artefacto";
+    ruta: string;
+};
+/** Lo que se manda al móvil, ya en su forma de salida; `undefined` = no sale. */
+export declare function filtrarSalida(mensaje: unknown): unknown | undefined;
+export declare function validarEntradaDelMovil(m: unknown): EntradaDelMovil | undefined;
+/**
+ * Lo máximo que se manda al móvil en UN mensaje, en bytes de su JSON. El relé cierra la conexión
+ * si el sobre pasa de `TOPE_DE_SOBRE` (1_000_000) y base64 + AES-GCM lo engordan ~33 %, así que
+ * se queda por debajo de ese tope dividido entre ~1,4. Pasarse no da un error legible: da un cierre.
+ */
+export declare const TOPE_DE_SALIDA_BYTES = 700000;
+/**
+ * Hace caber un mensaje de salida en el tope. Una `reemision` se recorta quitando los actos más
+ * VIEJOS (lo reciente es lo que el móvil necesita ver); cualquier otro que no quepa devuelve
+ * `undefined` y quien llama lo anota, porque partir una aprobación o un diff lo falsearía.
+ */
+export declare function ajustarATope(mensaje: unknown, tope?: number): unknown | undefined;
+/**
+ * Los artefactos que el móvil puede VER: imágenes, que son lo que pide quien sigue un turno desde el
+ * teléfono (las capturas del aparato). Un HTML o un `.openui` no: en el escritorio se sirven dentro de un
+ * iframe con dos capas de sandbox, y en la web móvil no hay con qué aislarlos.
+ */
+export declare const MIMES_DE_ARTEFACTO_AL_MOVIL: ReadonlySet<string>;
+/** Lo máximo que se manda de UN artefacto al móvil, en bytes del fichero: una captura cabe de sobra. */
+export declare const TOPE_DE_ARTEFACTO_AL_MOVIL = 6000000;
+/** Caracteres de base64 por trozo: con su sobre JSON queda por debajo de `TOPE_DE_SALIDA_BYTES`. */
+export declare const CARACTERES_POR_TROZO = 450000;
+export type MensajeDeArtefactoAlMovil = {
+    clase: "artefacto.trozo";
+    ruta: string;
+    mime: string;
+    indice: number;
+    total: number;
+    datos: string;
+} | {
+    clase: "artefacto.error";
+    ruta: string;
+    motivo: string;
+};
+/**
+ * Un artefacto partido en los mensajes que cruzan el puente: base64 en trozos que caben en el tope de
+ * salida (una captura pasa de él entera), en ORDEN —el canal cifrado los manda en cola, en el orden de
+ * llamada— y numerados para que el móvil los junte y sepa cuándo tiene todos.
+ */
+export declare function trozosDeArtefacto(ruta: string, mime: string, datos: Uint8Array): MensajeDeArtefactoAlMovil[];

package/dist/core/repartoDeEncargo.d.ts

@@ -0,0 +1,80 @@
+import type { Acto } from "./actos.js";
+import { type Tarea } from "./tareas.js";
+/**
+ * Repartir un encargo GRANDE en tareas de fondo que corren EN ORDEN (petición de la persona, 06-10-2026: «cuando le doy
+ * una tarea grande, por ejemplo el diseño de dos ventanas…»; plan en
+ * `docs/superpowers/plans/2026-10-06-tareas-encadenadas.md`).
+ *
+ * El orquestador PROPONE (`proponer_tareas`), con los diseños que necesita cada tarea; la persona ve cada una aumentada
+ * y editable y, al pulsar «Encolar en orden», se crean encadenadas por `Tarea.tras`. **Nada de aquí crea una tarea por su
+ * cuenta**: crear una tarea es la autorización para que escriba sin preguntar (CLAUDE.md § tareas), y esa la da la
+ * persona, también en modo autónomo. Puro.
+ */
+export declare const NOMBRE_PROPONER_TAREAS = "proponer_tareas";
+/** Un reparto de más tareas es otro plan, no un encargo repartido. */
+export declare const TOPE_DE_TAREAS_PROPUESTAS = 6;
+/** El mismo tope que el encargo aumentado (`agent/tareas/aumentador.ts#TOPE_DE_ENCARGO`). */
+export declare const TOPE_DE_PETICION = 8000;
+export interface TareaPropuesta {
+    titulo: string;
+    /** El encargo de ESA tarea, autosuficiente: la tarea no ve la conversación en que se propuso. */
+    peticion: string;
+    /** Los adjuntos de la sesión que necesita ESTA tarea (sus diseños), por nombre (`/adjuntos/x.zip` o `x.zip`). */
+    adjuntos?: string[];
+}
+export interface PropuestaDeTareas {
+    /** Por qué no cabe en un turno: se le enseña a la persona encima de las tareas. */
+    motivo: string;
+    tareas: TareaPropuesta[];
+}
+/** La propuesta en una línea, para la piel que no la pinta como tarjeta (stdio, la TUI). */
+export declare function textoDePropuesta(p: PropuestaDeTareas): string;
+/** El nombre de un adjunto sin el prefijo de su ruta virtual. */
+export declare const nombreDeAdjuntoPropuesto: (a: string) => string;
+/** Por qué la propuesta no vale, o `undefined`. Lo dice en palabras, para devolvérselo al agente. */
+export declare function motivoDePropuestaInaceptable(p: PropuestaDeTareas): string | undefined;
+/**
+ * Las `Tarea` de una propuesta aceptada: en estado `nuevo`, encadenadas por `tras` y con `creada` creciente (+1 ms cada
+ * una: el FIFO del corredor ordena por `creada`, y dos iguales no tienen orden). Sin adjuntos: los pone el servidor
+ * después de copiarlos, leyéndolos del disco como siempre.
+ */
+export declare function tareasEncadenadas(opciones: {
+    proyecto: Tarea["proyecto"];
+    /** `titulo` es el que puso el agente en la propuesta: deducirlo de la petición daba «Proyecto XOne
+     *  (app Android de…» en las dos (medido en la prueba real). Vacío cae a la petición. */
+    tareas: readonly {
+        titulo: string;
+        peticion: string;
+        encargo: string;
+    }[];
+    ahora: Date;
+    id: () => string;
+}): Tarea[];
+/**
+ * La propuesta `id` si está en el transcript y nadie la ha resuelto todavía; si no, `undefined`.
+ *
+ * Es la guarda del servidor antes de encolar o descartar: lo que se encola sale de AQUÍ —el acto
+ * que escribió la piel—, no de lo que mande el cliente, y una propuesta ya resuelta no se encola
+ * otra vez (dos pestañas, un doble clic).
+ */
+export declare function propuestaPendiente(actos: readonly Acto[], id: string): Extract<Acto, {
+    tipo: "propuesta-de-tareas";
+}> | undefined;
+/**
+ * Desde cuántas tareas un plan se RECUERDA al orquestador que puede repartirlo. Tres porque dos son a menudo «el cambio
+ * y su prueba», que caben en un turno; los planes medidos que no cabían traían seis y siete.
+ */
+export declare const TAREAS_PARA_RECORDAR_EL_REPARTO = 3;
+/**
+ * El aviso del HARNESS al orquestador cuando un especialista le deja un plan grande (`/planes/<slug>/TASKS.md`).
+ *
+ * Existe por una sesión real (Maset, rediseño del menú y pantalla de Entradas/Salidas): el orquestador vio que el encargo
+ * era «candidate for proponer_tareas», decidió esperar al plan del analista para saberlo, y con el plan ya escrito —seis
+ * tareas— siguió preguntando detalles sin volver sobre ello. La regla estaba en su prompt; un prompt no es un contador,
+ * así que el recordatorio va en código, en el informe del hijo, justo cuando el plan existe. No decide por él: si cabe en
+ * el turno, sigue.
+ */
+export declare function avisoDeReparto(planes: readonly {
+    ruta: string;
+    tareas: number;
+}[]): string | undefined;

package/dist/core/rubrica.d.ts

@@ -0,0 +1,78 @@
+/**
+ * La rúbrica: qué significa «hecho» en ESTE encargo, y qué se hace cuando no lo está.
+ *
+ * Portado del `RubricMiddleware` de deepagents, que existe en su SDK de **Python** y no en el
+ * de JS. El diseño es suyo y es bueno: en la parada natural del agente —el modelo contesta sin
+ * pedir más tools— un CALIFICADOR juzga lo hecho contra unos criterios, y si dice que falta
+ * algo su comentario vuelve como mensaje y el bucle sigue, con tope de vueltas.
+ *
+ * ## Qué es esto y qué NO es
+ *
+ * **No sustituye al verificador** (`turnoReal.ts#conVerificacion`), lo complementa, y la
+ * frontera es lo que cada uno puede saber. El simulador contesta lo OBJETIVO —esto parsea, este
+ * atributo existe, este JavaScript no revienta— y por eso su veredicto se puede creer. Un
+ * calificador contesta lo que el simulador no ve: si el título se lee entero, si se hizo lo que
+ * se pidió, si se cambió algo que nadie pidió. Medido hoy: un especialista cambió
+ * `editable="false"` por `locked="true"` dentro de un arreglo visual, y ninguna comprobación
+ * estática tiene nada que decir de eso.
+ *
+ * **Y por eso un rojo suyo no es el rojo del verificador.** El del simulador es una medida; éste
+ * es la opinión de un modelo sobre un transcript. Se dice con esas palabras donde se enseñe.
+ *
+ * ## Dos cosas del original que NO se copian
+ *
+ * - **Terminar sin satisfacer no puede ser mudo.** Ellos documentan que con `failed`,
+ *   `max_iterations_reached` o `grader_error` no tocan los mensajes, así que la última respuesta
+ *   es la del modelo y quien llama tiene que ir a mirar un campo privado del estado. Eso es el
+ *   mismo fallo que el tope de llamadas tenía aquí: trabajo que acaba a medias sin que nadie se
+ *   entere. Aquí el estado no satisfecho SE DICE.
+ * - **El calificador entra por un PUERTO**, no como un modelo construido dentro. Así esto se
+ *   prueba sin red ni clave, que es el invariante que sostiene el diseño de este repo.
+ *
+ * Puro: aquí está la política. Quién llama al modelo y quién monta el middleware es de `agent/`.
+ */
+/** Lo que el calificador puede decir. */
+export type Veredicto = "satisfecho" | "necesita-revision" | "fallido";
+/**
+ * Cómo acabó una evaluación. Los dos últimos no los dice el calificador: los dice el harness.
+ *
+ * `fallido` es «la rúbrica no se puede evaluar» —está mal escrita, o no habla de esto—, y es
+ * distinto de `error-del-calificador`, que es que el modelo no contestó. Uno culpa a la rúbrica
+ * y el otro al entorno, y mezclarlos manda a arreglar lo que no estaba roto.
+ */
+export type EstadoDeRubrica = Veredicto | "tope-de-vueltas" | "error-del-calificador";
+/** Un estado terminal cierra el bucle; `necesita-revision` es el único que lo continúa. */
+export declare function esTerminal(estado: EstadoDeRubrica): boolean;
+export interface Calificacion {
+    veredicto: Veredicto;
+    /** Qué falta, en palabras del calificador. Vacío con `satisfecho`. */
+    comentario: string;
+}
+/**
+ * Cuántas vueltas se le dan.
+ *
+ * Tres es el valor del original. **Aquí importa más que allí**: cada vuelta puede traer
+ * escrituras, y cada escritura pasa por una aprobación — así que un tope alto no es solo gasto,
+ * son paradas delante de una persona. Y en una tarea de fondo no hay nadie que frene el bucle,
+ * que es el mismo argumento por el que existen `TOPE_REPARACIONES` y el tope de tandas.
+ */
+export declare const TOPE_DE_VUELTAS = 3;
+/**
+ * El mensaje con que vuelve el trabajo al agente.
+ *
+ * Va con voz del HARNESS y no del usuario: quien lo lee tiene que saber que esto no es alguien
+ * pidiendo otra cosa, es una comprobación diciendo que lo pedido no está. Si se disfrazara de
+ * petición nueva, el agente podría tomarlo por un cambio de encargo y empezar otra cosa.
+ *
+ * Y dice de qué vuelta va: sin eso, tres mensajes iguales seguidos se leen como un bucle y el
+ * modelo no sabe cuánto margen le queda.
+ */
+export declare function mensajeDeRevision(comentario: string, vuelta: number, tope: number): string;
+/**
+ * Lo que se le dice a quien mira cuando el bucle acaba SIN satisfacer.
+ *
+ * Existe porque el original no lo tiene: allí el estado no satisfecho vive en un campo privado
+ * y la última respuesta sigue siendo la del modelo, que puede estar afirmando que terminó. Un
+ * trabajo que no cumple y lo dice como si cumpliera es peor que uno que falla.
+ */
+export declare function avisoDeNoSatisfecho(estado: EstadoDeRubrica, comentario?: string): string | undefined;

package/dist/core/rutaVirtual.d.ts

@@ -0,0 +1,29 @@
+/**
+ * La ruta REAL de una ruta VIRTUAL del backend del agente, o `undefined` si se sale del
+ * proyecto.
+ *
+ * El backend del agente es un `FilesystemBackend` con `virtualMode: true`, así que lo que el
+ * modelo escribe —y lo que llega en los argumentos de un `interrupt`— viene ROOTEADO en el
+ * proyecto: `/app.xne`, `/artefactos/x.html`. Es la forma que usan las descripciones de las
+ * tools, las skills y el predicado `seDetieneEn`.
+ *
+ * Y ahí estaba la trampa, medida: `resolve(raiz, "/app.xne")` devuelve `/app.xne`, porque una
+ * ruta absoluta DESCARTA la base. Quien leyera el disco así con la forma rooteada no
+ * encontraba nada — con la relativa sí, que es por lo que pasó desapercibido: el test que lo
+ * cubría usaba `"app.xne"` sin barra. En el ANTES del diff de una aprobación eso significaba
+ * un fichero existente enseñado como si fuera NUEVO, con sus líneas quitadas invisibles. Es
+ * el peor sitio posible para una media verdad: el diff de la aprobación es el único momento
+ * en que alguien ve lo que el agente va a escribir antes de que exista.
+ *
+ * Las dos formas se aceptan —la relativa y la rooteada— porque las dos funcionan contra el
+ * backend y por tanto las dos pueden llegar. Los separadores se normalizan antes de resolver:
+ * en POSIX `resolve` trata «\» como un carácter más del nombre, la misma lección que ya pagó
+ * `leerFicheroDeProyecto`.
+ *
+ * La contención se comprueba porque `..` sí puede salir del proyecto, y de aquí sale una
+ * lectura de disco: sin ella, el contenido de un fichero de FUERA acabaría en la pantalla de
+ * la aprobación. Es lexical y no `realpath` —esta función es pura y no toca disco—, así que
+ * quien necesite además cerrar los enlaces simbólicos recomprueba después, como hace
+ * `arbolDeProyecto.ts`.
+ */
+export declare function rutaRealDeVirtual(raiz: string, virtual: string): string | undefined;

package/dist/core/selectorDeCarpeta.d.ts

@@ -0,0 +1,59 @@
+/** Lo que tarda un diálogo en contestar lo pone una persona, así que el tope es largo: solo
+ *  existe para que un diálogo que nadie cierra no deje un proceso vivo para siempre. */
+export declare const TOPE_DEL_SELECTOR_MS: number;
+export interface ComandoDeSelector {
+    programa: string;
+    argumentos: readonly string[];
+}
+/**
+ * El comando que abre el selector, o AUSENTE si este sistema no tiene ninguno conocido.
+ *
+ * Ausente no es un fallo: es «aquí no hay selector», y entonces no se ofrece el botón. Un
+ * botón que no hace nada es peor que no tenerlo, y el campo de texto ya resuelve el caso.
+ *
+ * `desde` es dónde se abre el diálogo — la carpeta que hay puesta ahora, para no empezar en
+ * un sitio cualquiera. Se pasa como argumento SEPARADO, nunca interpolado en el guion de
+ * AppleScript: ahí dentro una comilla en un nombre de carpeta cerraría la cadena.
+ */
+export declare function comandoDelSelector(plataforma: string, desde?: string): ComandoDeSelector | undefined;
+/**
+ * La carpeta elegida, leída de lo que escupió el comando — o AUSENTE si no se eligió ninguna.
+ *
+ * **Cancelar no es un fallo y se cuenta igual que no elegir.** `osascript` sale con código 1
+ * y `zenity` con 1 cuando la persona cierra el diálogo, así que quien llama no puede
+ * distinguir un «no, gracias» de una avería por el código; lo que sí distingue es que no hay
+ * ruta, y con eso basta: el campo se queda como estaba.
+ *
+ * Se recorta el salto de línea final, que es del terminal y no del dato, y se exige que
+ * empiece por `/`: cualquier otra cosa que salga por ahí no es una carpeta y no se cuela
+ * hasta el validador disfrazada de ruta.
+ */
+export declare function carpetaDeLaSalida(salida: string): string | undefined;
+/**
+ * El comando que abre, en el explorador de ficheros del sistema, la carpeta que CONTIENE
+ * `ruta` — pensado para «enséñame dónde está este binario», no para elegir una carpeta.
+ *
+ * Los tres sistemas, sin lista cerrada que devuelva ausente: a diferencia del selector de
+ * arriba, `explorer.exe`/`open`/`xdg-open` existen en cualquier Windows, macOS o Linux de
+ * escritorio, así que no hace falta un tercer estado «este sistema no tiene».
+ *
+ * `dirname` y no `ruta` tal cual: `ruta` apunta al BINARIO (`…\platform-tools\adb.exe`), y
+ * lo que el botón promete es enseñar dónde vive, no intentar «ejecutar» la carpeta.
+ *
+ * **El `dirname` es el de `plataforma`, no el de este proceso.** `node:path` por omisión
+ * resuelve al del sistema donde CORRE el test, y una ruta de Windows partida con el
+ * `dirname` POSIX de un runner Linux/Mac no encuentra ninguna barra que cortar —
+ * `npm test` tiene que poder probar los tres sistemas desde uno solo.
+ *
+ * Pura: compone el comando. Lanzarlo es de `agent/config/selectorEnMaquina.ts`.
+ */
+export declare function comandoParaAbrirCarpeta(plataforma: string, ruta: string): ComandoDeSelector;
+/**
+ * El comando que abre ESA carpeta —no la que la contiene— en el explorador de ficheros del
+ * sistema. Es el de «ver los ficheros del proyecto» del resumen.
+ *
+ * En Windows la ruta se NORMALIZA a barras invertidas: la raíz de un proyecto sale de
+ * `rutaDeWorkspace`, que junta con `/` sobre una base de `\`, y `explorer.exe` no entiende una
+ * ruta mezclada — abre «Documentos» en su lugar, sin error que leer.
+ */
+export declare function comandoParaAbrirDirectorio(plataforma: string, carpeta: string): ComandoDeSelector;