xonecode 0.38.44 → 0.39.4

package/dist/core/serieDeEscrituras.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Una cola por CLAVE: dos tareas con la misma clave nunca se solapan; con claves distintas
+ * corren a la vez.
+ *
+ * **Por qué hace falta.** `write` y `edit` de un backend de ficheros son
+ * leer-modificar-escribir: leen el fichero entero, sustituyen y lo escriben entero. Dos a la
+ * vez sobre el MISMO fichero se pisan, y el modo de fallo es el peor que hay — las dos
+ * devuelven «bien» y una de las dos no está en el disco. Reproducido contra el backend real:
+ * cuatro `edit` concurrentes sobre un fichero, cuatro resultados sin error, **una** aplicada.
+ *
+ * **Y serializar SÍ basta, que era la duda razonable.** La objeción es que la segunda edición
+ * se resolvió contra un contenido que la primera acaba de cambiar, así que su `old_string`
+ * podría no valer ya. Cierto, y por eso esto va DEBAJO de quien edita y no encima: el backend
+ * vuelve a leer el fichero y vuelve a buscar el `old_string` cuando le toca su turno, así que
+ * el ancla se comprueba contra lo que hay. Medido con el backend de verdad:
+ *
+ * | | en paralelo | en serie |
+ * |---|---|---|
+ * | cuatro ediciones independientes | 1 aplicada, 0 errores | 4 aplicadas, 0 errores |
+ * | dos que se pisan | — | 1 aplicada, **1 error** |
+ *
+ * O sea que la edición que ya no encaja **falla en voz alta** en vez de perderse en silencio,
+ * y el modelo recibe su error y reintenta, que es el camino que este harness ya tiene.
+ *
+ * **Puro a propósito**: no sabe de ficheros ni de backends, solo de claves y de promesas. Así
+ * se prueba sin disco (`npm test` no toca la casa de nadie) y el mismo mecanismo sirve el día
+ * que haya otro recurso que no admita dos a la vez.
+ */
+/** Encola `tarea` detrás de lo que ya haya pendiente para `clave`. */
+export type EnSerie = <T>(clave: string, tarea: () => Promise<T>) => Promise<T>;
+/**
+ * Crea un serializador con su propia cola.
+ *
+ * Tres decisiones que no son de forma:
+ *
+ *  - **Un fallo NO envenena la cola.** La siguiente se encadena al resultado *saldado* de la
+ *    anterior, no a su promesa cruda: si la primera rechaza, la segunda corre igual. Lo
+ *    contrario convertiría un error de una escritura en el bloqueo de todas las siguientes
+ *    sobre ese fichero, que es un fallo mucho peor que el que esto viene a arreglar.
+ *  - **La entrada se RETIRA cuando se vacía**, comparando que la cola siga siendo la suya.
+ *    Sin eso el mapa crece con una entrada por fichero tocado y no se vacía nunca, en un
+ *    proceso que vive lo que dure la consola.
+ *  - **Devuelve lo que devuelva la tarea, y relanza lo que lance.** Esto es un turno de espera,
+ *    no un envoltorio que decide: si además cambiara el resultado, cada sitio que lo use
+ *    habría que volver a medirlo.
+ */
+export declare function crearSerieDeEscrituras(): EnSerie;
+/**
+ * Lo que se le DICE al modelo sobre escribir en paralelo, en la descripción de `write_file` y
+ * `edit_file` de los dos motores —una sola frase para los dos, para que no diverjan—.
+ *
+ * La cola de arriba hace que dos escrituras al mismo fichero no se pisen: es la CORRECCIÓN, y no
+ * depende de que el modelo obedezca. Esto es la otra mitad, la EFICIENCIA: sin decírselo, un
+ * modelo que agrupa `tool_calls` —DeepSeek lo hace, medido— pide cinco ediciones del mismo HTML
+ * en una respuesta; en fila, las que ya no encajan fallan y hay que reintentarlas. Lo que sí
+ * puede ir a la vez se dice también: prohibir el paralelismo entero tiraría lo que sí vale.
+ */
+export declare const REGLA_DE_ESCRITURAS_EN_PARALELO: string;

package/dist/core/settings.d.ts

@@ -0,0 +1,421 @@
+import { type Aviso } from "./config.js";
+import { type ModoDeEscritura } from "./modoDeEscritura.js";
+import { type DispositivoDeLaSesion } from "./dispositivoElegido.js";
+export interface Entorno {
+    id: string;
+    nombre: string;
+    /** La URL del MCP. Es lo que define el entorno. */
+    url: string;
+    scopes?: readonly string[];
+    /**
+     * Qué proyectos de este entorno se ENSEÑAN en la barra, por id.
+     *
+     * Es una preferencia de presentación y por eso vive con el entorno y no con el proyecto:
+     * un CloudStudio con doscientos proyectos no cabe en una barra lateral, y cuáles importan
+     * lo sabe la persona, no el servidor. **Ausente no es «ninguno»: es «no lo he dicho»**, y
+     * entonces manda la omisión (los primeros que devuelva el listado). Distinguirlo de una
+     * lista VACÍA —«no quiero ver ninguno», que es una elección legítima— es justo por lo que
+     * el campo es opcional en vez de arrancar en `[]`.
+     */
+    proyectos?: readonly string[];
+    /**
+     * Qué proyectos de este entorno van FIJADOS arriba de la barra, en su propio grupo, por id.
+     *
+     * Vive con el entorno por lo mismo que `proyectos`: es presentación y lo decide la persona.
+     * Es una lista APARTE y no una marca dentro de `proyectos` porque son dos preguntas: un
+     * fijado se enseña aunque no esté entre los visibles, y deja de pintarse en la lista de
+     * abajo. Aquí ausente y vacía significan lo mismo —ninguno fijado—.
+     */
+    fijados?: readonly string[];
+}
+/**
+ * Las cuatro clases de destino en que se prueba una app XOne. No son cuatro herramientas
+ * —`adb` sirve a la vez a los Android físicos y a los emuladores arrancados— sino las
+ * cuatro cosas distintas que una persona quiere mirar o dejar de mirar.
+ */
+export declare const PLATAFORMAS_DE_DISPOSITIVO: readonly ["android", "androidEmulador", "ios", "iosSimulador"];
+export type PlataformaDeDispositivo = (typeof PLATAFORMAS_DE_DISPOSITIVO)[number];
+/**
+ * Lo que se recuerda de UN AVD, por su NOMBRE y no por su serie: `emulator-5554`/`-5556`
+ * dependen del orden en que se arrancan, el nombre no. Ausente = nada que decir.
+ */
+export interface AjustesDeAvd {
+    /** El puerto LOCAL del túnel de hotswap (`adb forward tcp:<puerto> tcp:8443`). */
+    puerto?: number;
+    /** Arrancarlo sin ventana (`-no-window`). Solo `true` se guarda. */
+    sinVentana?: true;
+    /** De qué AVD salió, si se creó desde «Copia de». Ausente = los de antes o los creados fuera. */
+    copiaDe?: string;
+    /** Con `copiaDe`: se clonó CON lo instalado (y no solo la configuración). Solo `true` se guarda. */
+    clon?: true;
+}
+/**
+ * Qué destinos se MIRAN al medir la máquina.
+ *
+ * Vive en global y no en el proyecto porque describe el equipo, no la app: el mismo Mac
+ * mira los mismos simuladores para todos los proyectos que se abran en él.
+ *
+ * **Ausente no es «no»: es «no lo he dicho»**, y entonces se miran todos — la misma
+ * distinción que `Entorno.proyectos`, y por la misma razón: apagar un destino es una
+ * elección legítima que hay que poder distinguir de no haber elegido nunca. Por eso cada
+ * campo es opcional en vez de arrancar en `true`.
+ *
+ * Y apagar no es cosmético: medir cuesta procesos en el equipo del usuario —`adb devices`
+ * arranca el demonio de adb y se queda vivo, `xcrun` tarda segundos—, así que un destino
+ * apagado no se consulta, y su herramienta se declara «desactivada» en vez de fingir que
+ * no está.
+ *
+ * `rutaAdb`/`rutaEmulator` son la ruta a mano al binario, cuando `localizadorDeAndroid` no
+ * lo encuentra solo (PATH y SDK por omisión). Ausente = se sigue buscando como siempre.
+ * Son la SEGUNDA excepción declarada a `sinRutas`, igual que `Settings.workspace`: viajan
+ * ENTERAS por el cable (no abreviadas con `~` — eso se probó para el workspace y se
+ * descartó, ver `expandirConCasa`), y solo para `adb`/`emulator`; `xcrun`/`devicectl` se
+ * quedan en el host.
+ */
+export type AjustesDeDispositivos = {
+    [K in PlataformaDeDispositivo]?: boolean;
+} & {
+    rutaAdb?: string;
+    rutaEmulator?: string;
+    avds?: Record<string, AjustesDeAvd>;
+    /** El puerto del túnel de cada móvil físico Android, por su serie (IXCODE-32, `core/puertosDeAvd.ts`). */
+    fisicos?: Record<string, {
+        puerto?: number;
+    }>;
+};
+/** ¿Se mira este destino? Ausente = sí. */
+export declare function seMira(ajustes: AjustesDeDispositivos | undefined, plataforma: PlataformaDeDispositivo): boolean;
+/**
+ * ¿Está activa la depuración? Ausente = sí, mientras dure esta etapa de pruebas.
+ *
+ * Mismo molde que `seMira`: solo `false` apaga. Vive aquí, separado del campo crudo, para que
+ * quien resuelve el valor en vigor (`agent/turno/depuracion.ts#entornoConDepuracion`, y el
+ * cliente al pintar la casilla) no reimplemente la regla de la omisión cada vez.
+ */
+export declare function depuracionActiva(depurar: boolean | undefined): boolean;
+/**
+ * Tope máximo del selector de concurrencia de tareas en Ajustes. La omisión (sin nada
+ * guardado) es `CONCURRENCIA_POR_OMISION` de `core/tareas.ts` — 2 — y vive ahí y no aquí
+ * porque ese fichero es el dueño de la planificación; este solo guarda la ELECCIÓN.
+ */
+export declare const TOPE_DE_CONCURRENCIA_DE_TAREAS = 8;
+/**
+ * La sesión remota (móvil → esta consola por el puente de `xonecode-server`). EXPERIMENTAL y
+ * apagada por omisión: ausente o `habilitado` distinto de `true` = no hay botón en el chat ni se
+ * carga el paquete. Se activa con el interruptor de Ajustes → Sesión remota, que escribe
+ * `habilitado` (`docs/superpowers/specs/2026-10-09-sesion-remota-xonecode-design.md`).
+ */
+export interface AjustesDeRemoto {
+    habilitado?: boolean;
+    /** `wss://` a cualquier host, o `ws://` solo a loopback. Ausente = `SERVIDOR_REMOTO_POR_OMISION`. */
+    servidor?: string;
+    /** Por dónde sale la sesión: el servidor de XOne o un túnel de ngrok. Ausente = ngrok, salvo `servidor` escrito. */
+    via?: ViaRemota;
+    /** Solo con la vía `ngrok`: un dominio reservado en la cuenta (opcional). */
+    ngrok?: {
+        dominio?: string;
+    };
+}
+export type ViaRemota = "servidor" | "ngrok";
+export declare const SERVIDOR_REMOTO_POR_OMISION = "wss://remoto.xone.dev/ws";
+/** Lo que manda: `XONECODE_REMOTO=1` enciende para un arranque; si no, el `settings.json`. */
+export declare function remotoEnVigor(ajustes: AjustesDeRemoto | undefined, entorno: Record<string, string | undefined>): {
+    habilitado: boolean;
+    porEntorno?: true;
+    servidor: string;
+    via: ViaRemota;
+    dominio?: string;
+};
+export interface Settings {
+    entornos: Entorno[];
+    /** La carpeta donde se bajan las copias locales. La disposición de DENTRO la fija
+     *  `rutaDeWorkspace` y no es configurable. Ausente = `~/.xonecode/workspace`. */
+    workspace?: string;
+    /** Qué destinos se miran al medir la máquina. Ausente = todos. */
+    dispositivos?: AjustesDeDispositivos;
+    /**
+     * El tope de concurrencia de la cola de tareas en background: cuántas corren a la vez EN
+     * ESTA MÁQUINA. Vive aquí y no en el índice de tareas (`~/.xonecode/tareas/indice.json`)
+     * por el mismo motivo que `dispositivos`: describe el EQUIPO, no una tarea concreta, y el
+     * mismo Mac soporta la misma concurrencia para cualquier cola que corra en él.
+     *
+     * **Ausente no es «cero»: es «no lo he dicho»**, y entonces manda
+     * `core/tareas.ts#CONCURRENCIA_POR_OMISION` (2) — la misma distinción que
+     * `AjustesDeDispositivos` y que `Entorno.proyectos`. Cero SÍ se guarda: es una elección
+     * legítima (pausar la cola) y no se puede confundir con «no lo he dicho».
+     */
+    concurrenciaDeTareas?: number;
+    /**
+     * Deja las dos trazas opt-in (`XONECODE_TRACE_ERRORES`, `XONECODE_TRACE_TOOLS`) encendidas
+     * por omisión, para poder enterarse de un cuelgue como el hotswap en Windows sin tener que
+     * pedirle a nadie que teclee una variable de entorno primero. Vive en `core/` porque es la
+     * MISMA regla de las demás: se aplica en `agent/turno/depuracion.ts#entornoConDepuracion`.
+     *
+     * **Ausente no es «no»: es «no lo he dicho», y entonces manda ENCENDIDA** — al revés que
+     * `AjustesDeDispositivos` y que `concurrenciaDeTareas`, y a propósito: esto es diagnóstico de
+     * una etapa de pruebas, no una preferencia de máquina, y la omisión tiene que dejar rastro
+     * hasta que la 1.0 invierta el valor por defecto. Solo se guarda `false`, cuando alguien la
+     * apaga; volver a encenderla borra la clave en vez de escribir `true`.
+     */
+    depurar?: boolean;
+    /**
+     * El modo con que NACEN las sesiones nuevas de una persona en cualquier proyecto (IXCODE-31,
+     * Ajustes > General). Lo pisa el del proyecto (`config.json#modoDeEscritura`); ver
+     * `core/modoDeEscritura.ts#modoParaSesionNueva`. Ausente = supervisado, y por eso elegir
+     * supervisado BORRA la clave en vez de escribirla.
+     */
+    modoDeEscritura?: ModoDeEscritura;
+    /**
+     * El modelo de OpenCode (`proveedor/modelo`) para la prueba de Ajustes → Motores locales y para
+     * todo subagente de OpenCode sin `modelo:` en su `.md`, que manda sobre este. Sin él, OpenCode
+     * elige solo uno de su tier gratuito, que no contesta fuera de su consola (medido).
+     */
+    modeloDeOpencode?: string;
+    /** Ver `AjustesDeRemoto`. Ausente = la sesión remota no existe. */
+    remoto?: AjustesDeRemoto;
+    /**
+     * El aparato con que NACEN las sesiones nuevas —de una persona y de una tarea— en cualquier
+     * proyecto (IXCODE-51, Ajustes > General). Sin él, una sesión nueva no tiene aparato y los
+     * scripts prefieren un emulador. Es la FOTO, como la de la pastilla: un móvil desenchufado al
+     * abrir sigue siendo el elegido, y Ejecutar dice que no está en vez de cambiar a otro.
+     */
+    dispositivoPorDefecto?: DispositivoDeLaSesion;
+}
+/**
+ * Un entorno mal formado se DESCARTA en silencio; una credencial deja un AVISO grave y
+ * sigue. La asimetría es deliberada: un entorno roto es un dato de menos y el arranque
+ * puede seguir sin decir nada, pero una credencial en el fichero equivocado es un fallo de
+ * seguridad que tiene que verse — igual que hace `config.json` (`config.ts`, línea 112):
+ * un aviso «grave» que descarta el campo, no una excepción que tumbe el arranque. Este
+ * fichero antes lanzaba (`SettingsConCredencial`); se cambió a aviso porque `CLAUDE.md`
+ * exige que un fallo de CloudStudio no pueda tumbar el arranque de la consola.
+ */
+export declare function validarSettings(bruto: unknown): {
+    settings: Settings;
+    avisos: Aviso[];
+};
+/**
+ * Un segmento que no puede salirse de su carpeta ni inventar niveles.
+ *
+ * Exportada porque `web/servidor/sesiones.ts` necesita la misma guarda para el id de
+ * sesión, que llega del cliente y no puede componer una ruta: una segunda copia habría
+ * divergido de esta la primera vez que una se corrigiera y la otra no.
+ */
+export declare function segmentoSeguro(valor: string, que: string): string;
+/**
+ * Dónde queda la copia local de un proyecto: `<workspace>/<entorno>/<proyecto>`.
+ *
+ * El WORKSPACE es configurable (`settings.workspace`); la disposición de dentro NO, porque
+ * es lo que hace predecible encontrar una copia sin consultar un índice.
+ *
+ * **El literal `workspace` vivía aquí, en MEDIO** (`<base>/<entorno>/workspace/<proyecto>`),
+ * y se ha mudado a la omisión de la base (`~/.xonecode/workspace`). Dos motivos medidos:
+ * con la base en `~/.xonecode`, los ids de los entornos quedaban de HERMANOS de `agentes/`,
+ * `skills/`, `tareas/` y `auth.json` —la casa del harness mezclada con el trabajo—; y quien
+ * eligiera una carpeta suya se encontraba un nivel `workspace/` que no había pedido. Con el
+ * literal en la base, lo que se configura ES el workspace.
+ *
+ * **El segmento del ENTORNO se queda, y no es decoración**: el mismo nombre de proyecto
+ * existe a la vez en dos entornos, y sin ese nivel serían la misma carpeta (ver
+ * `Wizard.tsx`, que ya explica por qué un on-premise necesita id propio).
+ */
+/**
+ * ¿Esa raíz es una copia que creó xonecode, o una carpeta del usuario?
+ *
+ * De esto depende si el harness puede COMMITEAR solo al cerrar cada turno. En
+ * `<workspace>/<entorno>/<proyecto>` la carpeta la creó él y es suya; en la que abrió
+ * una persona —un proyecto offline, o `./bin/xonecode` dentro de su propio repo— un commit
+ * por turno sería ensuciarle el historial cada vez que habla con el agente.
+ *
+ * Compara por SEGMENTOS y no por prefijo de texto: `/casa/.xonecodeX` empieza por
+ * `/casa/.xonecode` y no tiene nada que ver. Y normaliza antes, porque una barra final o un
+ * `..` por medio hacen que dos rutas equivalentes no se parezcan como cadenas. La base a
+ * secas devuelve `false`: ahí no hay ningún proyecto, solo la carpeta que los contiene.
+ */
+export declare function dentroDelWorkspace(raiz: string, base: string): boolean;
+/**
+ * ¿Las dos rutas nombran la MISMA carpeta? Con la misma normalización que
+ * `dentroDelWorkspace` —por segmentos, y en Windows sin distinguir mayúsculas ni barras—,
+ * porque la raíz de una tarea se guardó en su día y la de hoy sale de `rutaDeWorkspace`: dos
+ * textos distintos para la misma copia no pueden dejar pasar un borrado.
+ */
+export declare function mismaRuta(a: string, b: string): boolean;
+/**
+ * Una ruta de Windows —`C:\…`, `C:/…` o `\\servidor\…`— se compara con `\` como separador y
+ * SIN distinguir mayúsculas, que es lo que hace su sistema de ficheros. Con `posix` a secas la
+ * ruta entera era UN segmento, así que en Windows nada estaba nunca «dentro del workspace»:
+ * el alta no podía vaciar la copia y los commits por turno no corrían. Se decide por la FORMA
+ * del texto y no por `process.platform`, para que el módulo siga puro y se pueda probar en cualquier
+ * máquina.
+ */
+export declare function esRutaDeWindows(ruta: string): boolean;
+/**
+ * Un `~/…` tecleado, resuelto contra la casa. Solo `~` y `~/…`: un `~otro` es la casa de
+ * OTRA persona en la sintaxis del shell, y aquí no se resuelve — se deja tal cual y se
+ * rechaza después por no ser absoluta.
+ *
+ * Es una comodidad de ENTRADA y nada más. **Lo que se enseña y lo que se guarda es la ruta
+ * ENTERA**: se probó a mandarla abreviada por el cable, para que el caso normal no llevara
+ * el nombre de la cuenta del sistema, y no se sostiene — la cabecera de esa misma consola ya
+ * saluda por el nombre del usuario, así que el `~` no tapaba nada que no estuviera ya, y a
+ * cambio dejaba en pantalla una ruta que no se puede comprobar de un vistazo, que es justo
+ * para lo que ese campo existe. `casa` entra por parámetro: este módulo es puro.
+ */
+export declare function expandirConCasa(ruta: string, casa: string): string;
+/**
+ * ¿Vale eso como workspace? Ausente = sí.
+ *
+ * Se comprueba sobre la ruta ya EXPANDIDA. Tres noes, y ninguno es de estilo: vacío no es
+ * una elección, una ruta relativa dependería del directorio desde el que se arrancó la
+ * consola —que no es el proyecto ni nada estable— y la raíz del disco convertiría cada id de
+ * entorno en una carpeta de primer nivel del sistema.
+ */
+export declare function motivoDeWorkspaceInaceptable(ruta: string): string | undefined;
+export declare function rutaDeWorkspace(base: string, entorno: string, proyecto: string): string;
+/**
+ * Qué entorno de `settings.json` sirve esta URL.
+ *
+ * Existe porque el `entorno` del `config.json` puede FALTAR o quedarse viejo, y las dos
+ * cosas mandaban el token al hueco equivocado:
+ *
+ *  - Falta en todo proyecto dado de alta desde la terminal, que no elige entorno. Esos
+ *    proyectos viven en `legado` hasta que alguien registra el oficial en el vestíbulo, y
+ *    entonces `adoptarLegadoSiProcede` MUEVE ese juego a `webstudio` y los deja sin tokens:
+ *    reautenticaban en silencio. Casando la URL leen el hueco adoptado y no se enteran.
+ *  - Se queda viejo cuando `/connect-studio` reescribe la `url` del proyecto: sin volver a
+ *    resolver, el `entorno` anterior seguiría nombrando el juego de OTRO servidor.
+ *
+ * La comparación normaliza con `URL` y cae a la comparación literal si alguna cadena no
+ * parsea. Qué absorbe esa normalización, MEDIDO y no supuesto: el case del host y el puerto
+ * por omisión explícito (`:443`) sí casan; una barra final de más, un `?` vacío, otro puerto,
+ * `http` frente a `https` y otro case en la RUTA no casan. Que no casen es benigno y no
+ * accidental: el fallo devuelve `undefined` —y cae en `legado`, donde ese proyecto ya
+ * estaba— en vez de resolver al id de otro entorno. Ninguna variante cruza a un id ajeno, y
+ * ESA es la propiedad de la que depende no mandarle a un servidor el token de otro.
+ */
+export declare function entornoDeUrl(url: string, entornos: readonly Entorno[]): string | undefined;
+/**
+ * Cuántos caracteres caben en el nombre de un entorno.
+ *
+ * Es un tope de PANTALLA, no de dato: el nombre se pinta en la pestaña de Ajustes y en la
+ * barra lateral, y ninguno de los dos es un párrafo. Se RECHAZA en vez de RECORTAR — un
+ * nombre cortado en silencio es el bug mudo de siempre, y quien lo escribió no se entera.
+ */
+export declare const LARGO_NOMBRE_DE_ENTORNO = 60;
+/**
+ * Por qué NO vale el nombre de un entorno, o `undefined` si vale.
+ *
+ * El nombre es un RÓTULO, no un identificador, y esa es toda la regla: el `id` sigue saliendo
+ * de la URL del servidor y sigue siendo la clave de todo —el segmento de la carpeta del
+ * workspace (`rutaDeWorkspace`), el hueco de sus credenciales de OAuth, el valor del
+ * `entorno` del `config.json` del proyecto y el valor que viaja por el cable—, así que aquí NO
+ * se aplica la regla de un slug. Espacios, acentos y mayúsculas valen: es la misma distinción
+ * que hace el `nombre` de un proveedor personalizado (`core/modelos.ts`), y por eso renombrar
+ * un entorno no mueve ninguna carpeta ni invalida ningún token.
+ *
+ * Un nombre VACÍO se rechaza, y no es una validación de formulario: `validarEntorno` DESCARTA
+ * un entorno sin nombre al cargar, así que dejarlo en blanco no deja un entorno «sin nombre» —
+ * lo hace DESAPARECER en el siguiente arranque, con sus credenciales y su carpeta colgando de
+ * un id que ya no está en ninguna lista. El motivo lo dice, porque la consecuencia no se
+ * adivina.
+ *
+ * Vive en `core/` porque la aplican los DOS lados: el servidor al guardar (y su negativa va en
+ * el 409, como la de `olvidar`) y el cliente para poder avisar sin haber ido al servidor. La
+ * frontera prohíbe compartir módulo, así que el cliente lleva su copia DECLARADA — la misma
+ * regla que `motivoDeWorkspaceInaceptable`.
+ *
+ * **Y NO se comprueba que no se repita**, que es una decisión y no un olvido: el nombre no es
+ * la clave, así que dos entornos que se llaman igual —el mismo servidor visto por dos redes, un
+ * clon de pruebas— se distinguen perfectamente por su `id`, y negarse obligaría a inventarse
+ * sufijos para algo que no está roto. Lo que sí hace falta es que la pantalla lo ADVIERTA, para
+ * que nadie acabe con dos pestañas idénticas creyendo que son cosas distintas.
+ */
+export declare function motivoDeNombreDeEntornoInaceptable(nombre: string): string | undefined;
+/**
+ * Por qué NO se puede quitar un entorno ahora mismo, o `undefined` si se puede.
+ *
+ * Se niega mientras algo VIVO depende de él: una consola abierta sobre una copia suya (su lazo
+ * sigue hablando con ese servidor) o una tarea de fondo que no ha terminado (la cola la
+ * abriría con un entorno que ya no está). Las copias de `<workspace>/<id>/` las reconoce por
+ * la RUTA, que es donde vive el id del entorno (`rutaDeWorkspace`). Lo que ya terminó no
+ * cuenta: quitar el entorno no borra nada del disco.
+ */
+export declare function motivoParaNoOlvidarEntorno(datos: {
+    entorno: string;
+    baseDeWorkspace: string;
+    abiertas: readonly string[];
+    tareas: readonly {
+        estado: string;
+        raiz: string;
+    }[];
+}): string | undefined;
+/**
+ * Por qué NO se puede borrar la copia local de un proyecto ahora mismo, o `undefined` si se
+ * puede.
+ *
+ * Es la hermana de `motivoParaNoOlvidarEntorno`, con una diferencia a propósito: una consola
+ * ABIERTA no es motivo. Quien borra la cierra antes (`vestibulo.borrarCopia`, el mismo orden
+ * que borrar la sesión abierta), y negarse obligaría a cerrar algo que la web no ofrece
+ * cerrar. Lo que sí para el borrado es lo que está ESCRIBIENDO ahí: un turno en vuelo —el
+ * agente tiene ficheros a medio escribir y su hilo en `checkpoint.sqlite`— o una tarea de
+ * fondo sin terminar, que la cola volvería a abrir sobre una carpeta que ya no existe.
+ */
+export declare function motivoParaNoBorrarCopia(datos: {
+    raiz: string;
+    trabajando: boolean;
+    tareas: readonly {
+        estado: string;
+        raiz: string;
+    }[];
+}): string | undefined;
+/**
+ * Por qué NO se puede guardar a mano un fichero en esa raíz ahora mismo (el editor de la pestaña
+ * Ficheros), o `undefined` si se puede.
+ *
+ * La hermana de `motivoParaNoBorrarCopia` con la misma idea —lo que importa es quién ESCRIBE ahí—
+ * y una diferencia: aquí no cuenta el índice de tareas sino las consolas VIVAS de este proceso,
+ * porque una tarea `requiere-atencion` espera feedback y no escribe. Dos fuentes:
+ *
+ * - una consola de persona de esa raíz con un turno en vuelo (no solo la del foco: puede haber
+ *   varias consolas vivas a la vez);
+ * - una consola de TAREA de esa raíz sin cerrar, o cerrada con el turno aún en vuelo.
+ *
+ * Con esto el guardado no necesita la cola de `escriturasEnSerie`: los únicos que escriben en la
+ * copia son los turnos y las tareas, y mientras corren se niega. **Límite declarado**: una tarea
+ * en OTRO proceso no se ve, el mismo que ya declara `borrarSesion`.
+ */
+export declare function motivoParaNoEditarFichero(datos: {
+    raiz: string;
+    personas: readonly {
+        raiz: string;
+        turnoEnVuelo: boolean;
+    }[];
+    tareas: readonly {
+        raiz: string;
+        cerrada: boolean;
+        turnoEnVuelo: boolean;
+    }[];
+}): string | undefined;
+/**
+ * Por qué NO se puede cambiar el workspace ahora mismo —y con él MUDAR las copias que hay
+ * dentro—, o `undefined` si se puede.
+ *
+ * La hermana de `motivoParaNoBorrarCopia` para TODA la base, con la misma diferencia a
+ * propósito: una consola ABIERTA y en reposo no es motivo. La web tiene siempre una en foco,
+ * así que negarse por ella haría el cambio imposible; quien muda la cierra antes, en el orden
+ * de `vestibulo.borrarCopia`. Lo que sí para la mudanza es lo que está ESCRIBIENDO en la base:
+ *
+ * - un turno en vuelo en cualquier copia de la base (`trabajando`: sus raíces);
+ * - una consola de TAREA abierta (`deTareas`), que no se cierra por nadie;
+ * - una tarea de fondo sin terminar con su raíz bajo la base vieja —`requiere-atencion`
+ *   incluida: espera feedback y la cola la volvería a abrir en la ruta de antes—.
+ */
+export declare function motivoParaNoMudarWorkspace(datos: {
+    base: string;
+    trabajando: readonly string[];
+    deTareas: readonly string[];
+    tareas: readonly {
+        estado: string;
+        raiz: string;
+    }[];
+}): string | undefined;

package/dist/core/shellDeAgente.d.ts

@@ -0,0 +1,177 @@
+/**
+ * El ENTORNO con el que corre la shell de un subagente con ejecución.
+ *
+ * TypeScript puro: aquí se decide QUÉ variables ve esa shell, y quien la monta es
+ * `agent/grafo/proyecto.ts`. Separado por lo de siempre —compuesto dentro del montaje, que
+ * todos los tests doblan, la regla quedaría escrita y no probada—, y porque esto es una
+ * decisión sobre secretos, que es justo lo que no puede depender de acordarse.
+ *
+ * **Lo que se quita, y por qué es obligatorio quitarlo.** `guardarCredencial` escribe la
+ * clave de API TAMBIÉN en `process.env`, a propósito (`agent/config/authEnDisco.ts`). Un
+ * `inheritEnv: true` a secas le pasaría esas claves a la shell del modelo, y entonces un
+ * `printenv` —que es lo primero que hace cualquiera para orientarse— las deja en el
+ * resultado de la tool, o sea en el contexto y en el `.jsonl` de la sesión. No es una fuga
+ * hipotética: es la salida normal de un comando normal.
+ *
+ * Se quitan **por la tabla** (`VARIABLES_POR_PROVEEDOR`, el único sitio donde vive el nombre
+ * de la variable de cada proveedor — hubo cuatro copias y ya habían divergido) más el
+ * prefijo `XONECODE_CLAVE_`, que es el de los proveedores PERSONALIZADOS y por definición no
+ * puede estar en ninguna tabla: el slug lo elige el usuario. Y no se quita todo lo que
+ * empiece por `XONECODE_`, que se llevaría `XONECODE_TRACE_TOOLS` y `XONECODE_MODELO` sin
+ * que sean secretos de nadie.
+ *
+ * **Límite declarado, y conviene no engañarse con él**: esto quita NUESTRAS credenciales,
+ * las que xonecode puso ahí. El entorno de quien arranca el proceso puede traer un
+ * `GITHUB_TOKEN` o un `AWS_SECRET_ACCESS_KEY` suyos, y eso no se filtra — ni se podría con
+ * honestidad, porque «lo que parece una clave» es una heurística y una heurística que falla
+ * en silencio es peor que una regla declarada. Quien concede ejecución concede leer el
+ * entorno y el disco; lo que esto evita es que el harness REGALE lo que él mismo escribió.
+ *
+ * **Y los scripts de una skill se ponen en el PATH, que es lo que quita el problema en vez de
+ * explicarlo.** Medido corriéndolo: el agente tenía DOS espacios de rutas —las virtuales de
+ * `read_file` y las reales de sus comandos— y se pasó decenas de llamadas mezclándolos, leyendo
+ * con `read_file` rutas absolutas que no existen para esa tool y no van a existir nunca. Con los
+ * `scripts/` de cada skill montada en el PATH, un script se llama por su NOMBRE
+ * (`xone-hotswap …`) y no hay ninguna ruta que acertar, ni que meter en el prompt, ni que viaje
+ * en el evento. Un aparato nuevo mañana trae su skill con sus scripts y quedan disponibles solos.
+ *
+ * **Se AÑADEN al final, no al principio.** Prepender dejaría que una skill —que puede venir en
+ * un `.zip` de cualquier sitio— sombreara un binario del sistema llamando a un script suyo `ls`
+ * o `git`. Al final, lo que ya existe gana.
+ *
+ * **Y lo que se AÑADE además son rutas, una variable por cosa.** Una shell ve el disco de verdad,
+ * no nuestras rutas virtuales: `/skills/xone-hotswap/` no existe para ella. Pero meter la
+ * ruta absoluta en el prompt tendría dos precios —el comando que el modelo componga sería el
+ * `detalle` del evento, y ahí no puede viajar una ruta de la máquina (`sinRutas`), y la
+ * raíz no es UNA sino tres con la del proyecto ganando—. Con una variable por skill, el
+ * prompt dice `$XONECODE_SKILL_XONE_HOTSWAP/scripts/android.mjs` y ni el contexto ni el
+ * cable ven una ruta.
+ */
+import { type DispositivoDeLaSesion } from "./dispositivoDeSesion.js";
+/**
+ * La variable que nombra la carpeta donde dejar lo que se quiera enseñar a una persona.
+ *
+ * Sin ella, un script escribe en el `cwd` —la raíz del proyecto— que es justo lo que
+ * `artefactoFueraDeSitio` prohíbe a las tools de fichero, y una shell no pasa por ahí.
+ */
+export declare const VARIABLE_DE_ARTEFACTOS = "XONECODE_ARTEFACTOS";
+/**
+ * Y la que nombra la carpeta donde dejar lo que **no** se le enseña a nadie: lo que un script
+ * saca del contexto para no metérselo al agente en el hilo (`core/hotswap.ts`).
+ *
+ * Son dos variables y no una porque son dos preguntas: la de arriba dice «dónde dejo lo que
+ * quiero que vea», ésta «dónde dejo lo que quiero poder releer». Con una sola, el script
+ * escribía sus volcados donde se anuncian — medido: diez tarjetas en el hilo, seis de ellas
+ * de ficheros que nadie volvió a abrir.
+ */
+export declare const VARIABLE_DE_HOTSWAP = "XONECODE_HOTSWAP";
+/**
+ * Cómo se llama la variable que lleva la ruta real de una skill.
+ *
+ * La MISMA derivación que `variableDeProveedor` para un personalizado (mayúsculas y los
+ * guiones a guión bajo): dos formas de convertir un slug en variable son dos formas de
+ * discrepar. El prefijo es otro a propósito — `XONECODE_SKILL_` frente a
+ * `XONECODE_CLAVE_`—, así que una skill no puede fabricarse el nombre de una credencial.
+ */
+export declare function variableDeSkill(nombre: string): string;
+/**
+ * Las dos rutas de Android que la shell necesita y no puede deducir.
+ *
+ * **Medido en la máquina de desarrollo**: `adb` está en el PATH (`/opt/homebrew/bin/adb`) y
+ * `emulator` **no** —vive en `.../share/android-commandlinetools/emulator/`— con
+ * `ANDROID_HOME` y `ANDROID_SDK_ROOT` vacías. O sea que el caso normal de un Mac con
+ * Homebrew es justo el que deja al agente sin el binario que arranca un emulador.
+ *
+ * Quien sabe dónde está el SDK es `localizadorDeAndroid` (`agent/dispositivos/`), que ya
+ * mira las dos variables de entorno y las raíces por omisión de cada plataforma. Pasarlo por
+ * aquí es lo que evita que el script tenga que adivinarlo: **una segunda regla sobre dónde
+ * vive el SDK es una segunda regla que puede divergir**, y ésta es la clase de cosa que falla
+ * en silencio —el script no encuentra el binario, el modelo se apaña por su cuenta—.
+ *
+ * Va por VARIABLE y no por el prompt por lo mismo que las skills: el comando que el modelo
+ * componga sale como `detalle` del evento, y ahí no puede viajar una ruta de la máquina
+ * (`sinRutas`).
+ */
+export declare const VARIABLE_DE_EMULATOR = "XONECODE_EMULATOR";
+export declare const VARIABLE_DE_ADB = "XONECODE_ADB";
+/**
+ * De un localizador de binarios del SDK a las variables que ve la shell.
+ *
+ * PURA y con el localizador por parámetro: así se prueba sin disco, y sobre todo así la
+ * composición de producción no vive dentro de `entornoDeLaShellDelProyecto` —que toca
+ * `process.env` y `existsSync`, y por tanto ningún test suyo podría ver si el localizador
+ * llegó a estar cableado—. Es el patrón de fallo que este repo lleva contadas nueve veces.
+ *
+ * Lo que no se encuentra **no sale**, ni siquiera como cadena vacía: la misma regla que el
+ * resto del módulo. Un `XONECODE_EMULATOR=""` no es «no consta», es una ruta rota que el
+ * script tomaría por buena.
+ */
+export declare function variablesDeAndroid(enSdk: (nombre: string, subcarpeta: string) => string | undefined): Record<string, string>;
+/** Una skill montada: su nombre de catálogo y dónde está DE VERDAD en el disco. */
+export interface SkillEnDisco {
+    nombre: string;
+    dir: string;
+}
+export declare function entornoDeShell(opciones: {
+    entorno: Readonly<Record<string, string | undefined>>;
+    skills?: readonly SkillEnDisco[];
+    /** La carpeta de artefactos de la sesión, si la sesión tiene una. */
+    artefactos?: string;
+    /** Y su hermana, la de los volcados que no se anuncian. Misma condición: si la hay. */
+    hotswap?: string;
+    /** El FICHERO con el dispositivo de la sesión (`core/dispositivoDeSesion.ts`). Misma
+     *  condición: solo con sesión. Se da la ruta aunque el fichero no exista todavía. */
+    dispositivo?: string;
+    /**
+     * Las carpetas de scripts que hay que poner al alcance, ya comprobadas por quien toca el
+     * disco: esto es puro y no mira si existen. Una que no exista no rompe nada, pero ensucia
+     * el PATH con una promesa vacía.
+     */
+    binarios?: readonly string[];
+    /**
+     * Las rutas de Android ya resueltas (`variablesDeAndroid`). Entran hechas y no como un
+     * localizador para que esto siga sin tocar disco.
+     */
+    android?: Readonly<Record<string, string>>;
+    /**
+     * El sistema: en Windows el PATH se llama `Path` y se separa con `;` (con `:` partiría `C:\…`). Por omisión, el de este
+     * proceso; por parámetro para probarlo sin estar en Windows.
+     */
+    plataforma?: string;
+}): Record<string, string>;
+/**
+ * Por qué un comando de quien ejecuta NO se lanza, o `undefined` si se lanza: una búsqueda que recorre el DISCO ENTERO.
+ *
+ * Medido en calc14: el conductor buscaba un script que el plan nombraba y no existe (`xone-validate`) y lanzó
+ * `find / -name "xone-validate*"`, que tardó más de cuatro minutos con el turno parado; luego otro `find /` para la carpeta
+ * del plan, que es virtual y no está en el disco con ese nombre. Nada de lo que busca vive fuera del proyecto, de sus
+ * variables o de su PATH, y recorrer la máquina del usuario es además mirar donde no le toca. Se reconoce `find`, `grep -r`
+ * y `ls -R` / `du` cuando su punto de partida es la raíz, la casa o una carpeta del sistema; lo relativo (`find .`) y lo de
+ * sus variables (`$XONECODE_…`) pasan. Es una lista de lo que se ha visto, no un filtro de shell: un límite declarado.
+ */
+export declare function motivoDeComandoRechazado(comando: string): string | undefined;
+/**
+ * Un comando que iría a OTRO aparato que el de la sesión (IXCODE-32), o `undefined` si no.
+ *
+ * El síntoma, de un usuario: con un móvil físico elegido, a mitad de sesión el trabajo pasó al
+ * emulador. Los scripts de `xone-hotswap` ya se niegan (`lib/dispositivo.mjs`); esto cierra la otra
+ * puerta, que es `adb` a mano en la shell. La regla es la que se pidió: **el aparato elegido se pasa
+ * SIEMPRE** —todo `adb` que actúe sobre un aparato lleva el `-s` de la sesión—, y con un físico o un
+ * iPhone elegido no se lanza un emulador. Lo que no toca un aparato (`adb devices`, `version`…) pasa.
+ *
+ * Como `motivoDeComandoRechazado`, mira palabras y no es un intérprete de shell: un `adb` dentro de
+ * un script propio, o un `ANDROID_SERIAL=` puesto a mano, no se ven. Límite declarado; tampoco mira
+ * el `--udid` de un `xcrun simctl` (los scripts de iOS sí).
+ */
+export declare function motivoDeOtroAparato(comando: string, d: DispositivoDeLaSesion | undefined): string | undefined;
+/**
+ * Lo que la traza dice del entorno de la shell de un agente (`DiagnosticoDeTools.entorno`), sin copiar el entorno: la
+ * clave del PATH (en Windows es `Path`), cuántas carpetas, si alguna tiene `node`/`adb` y cuántas son de scripts. `existe`
+ * mira el disco: entra por parámetro para que esto siga siendo puro.
+ */
+export declare function resumenDelEntorno(entorno: Readonly<Record<string, string>>, opciones: {
+    plataforma: string;
+    existe: (ruta: string) => boolean;
+    scripts?: number;
+    nodeDelServidor?: string;
+}): Record<string, string | number | boolean>;