xonecode 0.38.44 → 0.39.2

package/dist/agent/sesiones/checkpointer.d.ts

@@ -0,0 +1,146 @@
+import type { BaseCheckpointSaver } from "@langchain/langgraph-checkpoint";
+import { type ResultadoDePoda } from "../../core/podaDeCheckpoint.js";
+/**
+ * El checkpointer PERSISTENTE de un proyecto: la memoria del agente entre arranques.
+ *
+ * Hasta aquí el hilo vivía en un `MemorySaver` que moría con el proceso, así que reabrir
+ * una sesión era RELEER —la conversación a la vista y el agente sin recordar nada—, y la
+ * interfaz lo decía con el aviso de «conversación reabierta». Con esto el hilo sobrevive.
+ *
+ * Seis decisiones, y ninguna es de conveniencia:
+ *
+ * - **Uno por PROYECTO, no por sesión**, particionado por `thread_id`. Es la forma que la
+ *   librería asume —`deleteThread(threadId)` existe justamente para eso— y evita tener
+ *   tantos ficheros y tantas conexiones abiertas como conversaciones guardadas.
+ * - **El `thread_id` ES el id de la sesión.** Sin esa igualdad no hay nada que reanudar: al
+ *   reabrir hay que preguntar por la misma cadena con la que se escribió. Por eso el id de
+ *   sesión pasa a decidirse al ABRIR (`web/servidor/vestibulo.ts`) y no en el primer
+ *   volcado — lo que sigue siendo perezoso es la entrada del índice, que es lo que
+ *   ensuciaría la barra con sesiones vacías.
+ * - **Dentro de `.xonecode/`**, que está denegada al agente (`permisosDe`), excluida del
+ *   diff de Revisión y no sube nunca a CloudStudio. No es cosmético: un checkpoint lleva la
+ *   lista de mensajes ENTERA —los argumentos de cada tool, el contenido de cada
+ *   `write_file`, la respuesta de cada tool remota—, o sea justo lo que el transcript de
+ *   `sesiones.ts` no puede llevar por construcción. Este fichero es de la misma clase que
+ *   `auth.json` y por eso se crea con modo **0600**.
+ * - **WAL viene de serie** (medido contra `better-sqlite3` 13.0.3: `journal_mode` es `wal`
+ *   nada más abrir), que es lo que hace que dos procesos sobre el mismo proyecto —una
+ *   consola de terminal y la web— no se pisen. Con `MemorySaver` el problema no existía
+ *   porque cada proceso tenía el suyo.
+ * - **La consola de TERMINAL no lo usa.** Su hilo es un uuid nuevo en cada arranque y no hay
+ *   índice de sesiones donde reanudarlo, así que persistirlo solo dejaría hilos que nadie
+ *   puede volver a abrir engordando el fichero. Persistir es de quien tiene identidad que
+ *   reanudar; ahí sigue el `MemorySaver`, que además es la omisión de `construirAgente`.
+ * - **Un fallo al abrirlo no puede tumbar el turno.** Devuelve `undefined` y quien llama
+ *   cae al checkpointer en memoria: se pierde la memoria entre arranques, que es lo que ya
+ *   pasaba, y se dice — nunca se pierde la conversación en curso.
+ *
+ * Y dos cosas MEDIDAS, no deducidas, que cambian lo que hay que hacer:
+ *
+ * - **Una aprobación que se quedó sin contestar rompía el primer mensaje tras reabrir**, y
+ *   la primera medida no lo vio porque usaba la forma de grafo equivocada. Con un grafo de
+ *   un nodo, donde `START` va al nodo interrumpido, llegar con un mensaje humano normal
+ *   reejecuta ese nodo y vuelve a preguntar: inofensivo. El grafo del agente no tiene esa
+ *   forma —`START` va al MODELO y el nodo parado es el de tools—, así que lo que le llegaba
+ *   al modelo era `human → ai(tool_calls) → human`, con un `AIMessage` de llamadas y ningún
+ *   `ToolMessage` detrás: Gemini y OpenAI rechazan exactamente eso. Lo arregla
+ *   `turnoReal.ts#saldarAprobacionesHuerfanas` al abrir, no una guarda aquí: marcar como
+ *   histórico un hilo con tareas pendientes sería negar una sesión que sí puede continuar.
+ * - **Los acompañantes heredan el modo, y eso está comprobado.** SQLite escribe además
+ *   `checkpoint.sqlite-wal` y `-shm`, que crea él y no nosotros: medido sobre un proyecto
+ *   de verdad, los dos salen `-rw-------` como el fichero principal, porque los crea con
+ *   los permisos de la base. Así que poner el modo ANTES de abrir vale también para ellos —
+ *   con el `chmod` de después habrían salido a 0644.
+ */
+export declare function rutaDelCheckpointer(raiz: string): string;
+export declare function crearCheckpointerDeProyecto(raiz: string): BaseCheckpointSaver | undefined;
+/**
+ * Suelta la conexión de ESE proyecto y la saca del mapa, si la había.
+ *
+ * Existe por borrar la copia local: el mapa de arriba no cierra nunca —es a propósito, una
+ * conexión por proyecto para toda la vida del proceso—, y en Windows un `checkpoint.sqlite`
+ * abierto (y su `-wal`) hace que borrar la carpeta falle con `EBUSY`. Quien borra cierra antes
+ * la consola de esa raíz y DESPUÉS llama aquí: el turno ya no puede estar escribiendo. La
+ * siguiente `crearCheckpointerDeProyecto` sobre esa raíz abre una conexión nueva.
+ */
+export declare function cerrarCheckpointerDeProyecto(raiz: string): void;
+/**
+ * ¿Hay algo guardado de ese hilo?
+ *
+ * Es lo que convierte `historica` en un hecho comprobado en vez de en «se reabrió»: una
+ * sesión con checkpoint continúa de verdad, y una sin él —la de antes de que esto
+ * existiera, o una cuyo primer turno nunca llegó a correr— sigue siendo una relectura y se
+ * dice. Un fallo al preguntar se responde `false`, que es el lado conservador: enseñar el
+ * aviso de más es peor que prometer una memoria que no está.
+ */
+export declare function hayCheckpoint(checkpointer: BaseCheckpointSaver | undefined, hilo: string): Promise<boolean>;
+/**
+ * Olvida el hilo de una sesión borrada. Sin esto, borrar una conversación dejaría su
+ * memoria entera —con el contenido de los ficheros que se escribieron en ella— viva en el
+ * fichero del proyecto para siempre, invisible desde la interfaz.
+ */
+export declare function olvidarHilo(checkpointer: BaseCheckpointSaver | undefined, hilo: string): Promise<void>;
+/**
+ * Lo que ocupa esto en disco, o `undefined` si no hay base todavía.
+ *
+ * **Y el `-wal` CUENTA, que es la trampa.** Este checkpointer corre en modo WAL —viene de
+ * serie y es lo que deja que la web y el terminal no se pisen—, así que lo recién escrito
+ * vive en `checkpoint.sqlite-wal` hasta que SQLite lo consolida. Mirando solo el fichero
+ * principal, una base con cientos de MB todavía en el WAL contesta que ocupa 4 KB y la cota
+ * no dispara nunca: la regla queda escrita y muerta, con todo en verde. Se descubrió porque
+ * el test que exige que el fichero ENCOJA daba `4096` antes y después.
+ *
+ * El `-shm` no entra: son 32 KB de índice compartido, no datos.
+ */
+export declare function tamanoDelCheckpointer(raiz: string): number | undefined;
+/**
+ * Adelgaza el `checkpoint.sqlite` de un proyecto: borra lo que ya no reanuda y compacta.
+ *
+ * Cuatro decisiones, y ninguna es de conveniencia:
+ *
+ * - **Sobre la conexión que YA existe**, la de `crearCheckpointerDeProyecto`. Abrir una
+ *   segunda sería competir con nosotros mismos por un lock exclusivo que `VACUUM` necesita.
+ * - **El borrado va en una transacción y el `VACUUM` FUERA**, porque SQLite no lo admite
+ *   dentro de una. Si el `VACUUM` no entra, el borrado ya está hecho y el fichero encoge en
+ *   el siguiente — lo que se pierde es la devolución del espacio, no la corrección.
+ * - **Fail-soft con el cerrojo.** `VACUUM` reescribe el fichero entero y en este repo puede
+ *   haber dos procesos sobre el mismo proyecto (la web y el terminal). Un `SQLITE_BUSY` no
+ *   es un error que contar: esto es mantenimiento, y la vuelta siguiente llega al cerrar el
+ *   turno que viene. Por eso NUNCA lanza.
+ * - **No comprueba la cota**: eso es `debePodar` y vive en `core/`. Aquí solo se ejecuta,
+ *   para que la regla se pueda probar sin una base delante.
+ *
+ * Medido sobre el fichero real de 879 MB: 2.794 checkpoints → 44, y 20,9 MB, en 2,5 s. El
+ * hilo sigue vivo en los dos sentidos —se relee igual y admite un `put` nuevo—.
+ */
+export declare function podarCheckpointer(checkpointer: BaseCheckpointSaver | undefined, raiz: string): ResultadoDePoda | undefined;
+/**
+ * ¿Hay trabajo del grafo a medias en cualquier parte de la base?
+ *
+ * **La señal son los `writes` colgados del ÚLTIMO checkpoint de un espacio.** Un `write` es
+ * el resultado de un paso que todavía no se ha doblado en un checkpoint nuevo, así que sobre
+ * el último significa que el grafo se paró ahí: típicamente un subagente esperando una
+ * aprobación, que es justo el caso que no se puede podar. Los miles de `writes` de una sesión
+ * cerrada cuelgan de checkpoints ANTERIORES y no cuentan.
+ *
+ * Se pregunta por la base ENTERA y no por el hilo del turno que acaba de cerrar: en un
+ * proyecto hay varias sesiones y una puede estar parada en una aprobación mientras otra
+ * trabaja. Si algo está pendiente en cualquier sitio, no se poda nada y se vuelve a intentar
+ * al cerrar el turno siguiente — esto es mantenimiento, no una operación que urja.
+ *
+ * **Un fallo al preguntar contesta `true`**, o sea «no se poda»: es la dirección conservadora,
+ * la misma de `hayCheckpoint` por el otro lado.
+ */
+export declare function hayPendientesEnLaBase(checkpointer: BaseCheckpointSaver | undefined): boolean;
+/**
+ * La poda de MANTENIMIENTO: mira la cota y poda solo si toca. Es lo que se engancha al cierre
+ * del turno.
+ *
+ * **El orden importa y es el barato primero**: un `statSync` (microsegundos) decide el caso
+ * normal, y solo si pasa de la cota se le pregunta a la base si hay algo a medias. Al revés,
+ * cada turno pagaría una consulta para tirarla.
+ *
+ * Nunca lanza: esto corre en el `finally` de un turno, y un mantenimiento que reviente el
+ * cierre es peor que un fichero grande.
+ */
+export declare function mantenimientoDelCheckpointer(checkpointer: BaseCheckpointSaver | undefined, raiz: string): ResultadoDePoda | undefined;

package/dist/agent/sesiones/git.d.ts

@@ -0,0 +1,66 @@
+/** Las tres clases de cambio que le importan a xonecode. No hay una cuarta. */
+export type ClaseDeCambio = "nuevo" | "modificado" | "borrado";
+/**
+ * Índice de git propio y temporal, para poder construir un árbol (`git add` + `write-tree`
+ * o `commit-tree`) sin pasar por el índice de verdad.
+ *
+ * Existe porque el usuario puede tener trabajo a medias en SU staging cuando xonecode
+ * necesita fotografiar el árbol (al empezar un turno, o al hacer un `/sync`) — tocárselo
+ * sería imperdonable: perdería la frontera entre lo que él decidió `add`-ear y lo que no.
+ * Un índice aparte, en un directorio temporal que se limpia al terminar, dejar hacer todo
+ * esto sin que el índice real se entere de que existió.
+ *
+ * `etiqueta` solo distingue el prefijo del directorio temporal entre llamadores (útil para
+ * reconocer de quién es un directorio huérfano si algo no limpia bien); no cambia el
+ * comportamiento.
+ */
+export declare function indicePrivado(etiqueta: string): {
+    ruta: string;
+    limpiar: () => void;
+};
+/**
+ * Saca `.xonecode` de un índice PRIVADO recién construido con `git add -A`.
+ *
+ * Va aquí y no en un pathspec del `add` porque ese camino está medido y no vale: `git add`
+ * con `:(exclude).xonecode` en un repo donde la carpeta YA está ignorada —el caso normal,
+ * `prepararRepo` escribe `info/exclude`— da por nombrada una ruta ignorada y **sale con
+ * código 1**. `rm --cached` con `--ignore-unmatch` funciona en los dos casos y no dice nada
+ * cuando no había qué quitar.
+ *
+ * Y hace falta desde que ahí dentro vive el checkpointer: en un proyecto CLOUD la carpeta
+ * está excluida y esto es un no-op, pero en modo OFFLINE sobre el repo del usuario nadie
+ * escribió ese exclude —lo dice la cabecera de `sesionGit.ts`—, así que cada foto metía
+ * `checkpoint.sqlite` entero en `.git/objects`. Con `MemorySaver` eran unos KB de `.jsonl`
+ * y no se notaba; medido hoy, ese fichero son 30 MB que cambian en cada superpaso, y las
+ * refs `refs/xonecode/sesion/*` mantienen vivo cada blob para siempre.
+ *
+ * No cambia lo que se REPORTA en un proyecto cloud (ya no salía), y en uno offline alinea
+ * las dos vistas: `sesionGit.ts` ya excluye `.xonecode` de sus diffs a propósito.
+ */
+export declare function sacarXonecodeDelIndice(ejecutar: (cmd: string, args: string[], opciones: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => Promise<unknown>, raiz: string, indice: string): Promise<void>;
+/**
+ * Traduce la marca de una línea de `git diff --name-status` (la primera letra: `A`, `M`,
+ * `D`, `R100`, …) a una de las tres clases de `Cambio`/`CambioLocal`.
+ *
+ * Esto es la parte que había divergido: `gitSync.ts` mapeaba `T` (cambio de tipo, p.ej.
+ * fichero → symlink) a `modificado` pero DESCARTABA en silencio cualquier marca que no
+ * reconociera; `instantanea.ts` no mapeaba `T` pero usaba `?? "modificado"` como omisión
+ * para lo desconocido. La regla unificada, pensada por caso de uso y no promediada:
+ *
+ * - `A` es alta limpia (`nuevo`) y `D` es baja limpia (`borrado`): son las dos únicas
+ *   marcas que hay que distinguir de un cambio de contenido, porque de ellas depende el
+ *   candado de `planDeSubida` (solo se borra lo que se descargó) y el alta/baja del plan.
+ * - CUALQUIER OTRA MARCA —`M`, `R`, `C`, `T`, o una que git añada mañana y que hoy no
+ *   conocemos— se trata como `modificado`. Para `instantanea.ts` (la foto del ANTES: solo
+ *   alimenta el deshacer y el diff que lee el modelo) tratar de más como "cambiado" cuesta,
+ *   como mucho, una línea de diff rara. Para `gitSync.ts` (el plan de subida) la alternativa
+ *   —descartar la línea, que es lo que hacía antes— es el peor fallo posible: una marca
+ *   perdida es un fichero que ni sube ni se borra en CloudStudio, y nada avisa de ello. Entre
+ *   "invisible por defecto" y "visible por defecto", esto último es lo seguro en los dos
+ *   sitios, así que gana en los dos. `T` en concreto sigue el mismo criterio: es un cambio
+ *   de contenido (el fichero pasó de ser una cosa a ser otra), no un alta ni una baja.
+ */
+export declare function claseDeCambio(marca: string): ClaseDeCambio;

package/dist/agent/sesiones/gitSync.d.ts

@@ -0,0 +1,264 @@
+import type { CambioLocal } from "../../core/planDeSubida.js";
+export declare const REMOTO = "cloudstudio";
+/**
+ * Si la carpeta es la RAÍZ de su propio repo, y no una subcarpeta del repo de otra.
+ *
+ * `esRepo` contesta «sí» si CUALQUIER ancestro es un repo, y para `prepararRepo` eso es la
+ * diferencia entre una copia con su historia y una que escribe en la de otro: sin su propio
+ * `git init`, el baseline y los commits de cada turno acababan en el repo de arriba, donde
+ * todo el proyecto es nuevo — y Revisión lo enseñaba entero como «añadido por esta sesión».
+ * Se compara con el camino REAL (`realpath`), porque `--show-toplevel` lo devuelve resuelto.
+ */
+export declare function esRepoPropio(raiz: string): Promise<boolean>;
+/**
+ * Deja la copia VACÍA para bajarla entera: borra todo lo que cuelga de la raíz salvo
+ * `.xonecode/` —sesiones, checkpoint, memoria—, y el `.git` también.
+ *
+ * Es lo que hace «Actualizar repo local» desde que se decidió que la copia tiene que quedar
+ * IDÉNTICA a la rama y con un git recién hecho, no con el zip escrito encima: así lo borrado
+ * en Studio desaparece también aquí, y el primer commit es el de la bajada.
+ *
+ * **Solo dentro del workspace, comprobado aquí y no solo por quien llama**: en la carpeta que
+ * abrió una persona esto le borraría su trabajo y su historia. Por el TEXTO de la ruta y por
+ * el camino REAL, como el resto de guardas, porque un enlace dentro del workspace que apunte
+ * fuera pasaría la primera. No se baja por un enlace: `rmSync` sobre un enlace quita el enlace.
+ */
+export declare function vaciarCopia(raiz: string, baseDeWorkspace: string): string[];
+/**
+ * Deja el repo listo tras una descarga: repo, exclusiones, remoto y baseline.
+ *
+ * El commit de baseline se construye con índice privado para no tocar el staging del
+ * usuario, que puede tener trabajo a medias cuando hace un `/sync`.
+ *
+ * **En un repo PREEXISTENTE la configuración es suya, no nuestra.** Se cuida su índice
+ * con esmero (`indicePrivado`, la guarda antes del `reset --mixed`) y pisarle la config
+ * sin la misma guarda sería incoherente: un repo con `origin` en GitHub acababa con su
+ * rama apuntando a un remoto `cloudstudio://` que no es ningún servidor git, y su
+ * `git push` dejaba de funcionar. Las claves que ya tienen valor se respetan y se DICE
+ * cuáles se omitieron: un aviso que no se da es un cambio invisible en el repo de otro.
+ */
+/**
+ * Lo que este repo no tiene que ver: la carpeta del harness y la basura del sistema.
+ *
+ * **Va en `info/exclude` y NUNCA en `.gitignore`**, y no es una preferencia: `.gitignore` es
+ * un fichero del PROYECTO, así que el plan de subida lo vería como una alta y acabaría
+ * dentro de la app XOne del cliente. `info/exclude` es local del repo y no viaja a ninguna
+ * parte.
+ *
+ * Dos grupos:
+ * - **`.xonecode/`**, donde escribe el propio harness. La exclusión se ancla al PROYECTO: en
+ *   un repo mayor, `.xonecode/` a secas excluiría también el de cualquier otro subdirectorio
+ *   del usuario. La `/` inicial es relativa a la raíz del repo, que es donde git lo lee.
+ * - **La basura del SO**, que sí va sin anclar —un `.DS_Store` es basura esté donde esté— y
+ *   que entró aquí midiendo: sin ella, el `git add -A` de `commitDeTurno` se la tragaba, y
+ *   como `cambiosPendientes` compara la ref remota contra el árbol, el fichero del Finder
+ *   salía en el plan de `/sync subir` como una alta y `subida.ts` lo habría escrito en la app
+ *   del cliente. De paso arregla la otra mitad: hasta ahora un `.DS_Store` suelto bastaba
+ *   para que la guarda de árbol limpio se negara a subir.
+ *
+ * Es idempotente y **solo AÑADE lo que falte**, línea a línea: el fichero puede tener
+ * patrones del usuario y de una versión anterior de esto.
+ */
+export declare function asegurarExclusiones(raiz: string): Promise<void>;
+export declare function prepararRepo(raiz: string, ramaOrigen: string, informar?: (texto: string) => void, 
+/**
+ * `propio`: exigir que el repo sea DE ESTA carpeta y, si no, hacer su `git init` aquí.
+ * Solo lo pide la bajada que VACÍA una copia del workspace: ahí la copia es de XOneCode y
+ * tiene que tener su historia, y sin esto una copia que cuelga del repo de otra carpeta
+ * escribiría el baseline y los commits por turno en la historia de arriba — donde todo el
+ * proyecto es nuevo y Revisión lo enseña entero como «añadido». Ausente es lo de siempre,
+ * y es a propósito: un proyecto que una persona abre DENTRO de su repo usa ese repo.
+ */
+modo?: {
+    propio?: boolean;
+}): Promise<string>;
+/**
+ * Lo que hay en local y no está subido: el diff contra la ref de seguimiento de LA rama,
+ * `refs/remotes/cloudstudio/<rama>`.
+ *
+ * Una sola rama, en los dos sentidos: se baja de `config.rama` y se sube a `config.rama`.
+ * Hubo una rama de trabajo (`xonecode/<origen>`, con su propia ref y su `crearRama` en el
+ * servidor) para no escribir en la rama que el cliente tiene abierta en Studio; el precio
+ * era que lo que se subía vivía en un sitio que nadie mira, y la rama del proyecto se
+ * quedaba quieta. Lo que se pide es aplicar cambios y subirlos a la rama de la que se bajó
+ * el proyecto, así que la ref es UNA — y `prepararRepo` la escribe en cada bajada (y en el
+ * alta), que es justo el estado con el que se compara esto.
+ */
+export declare function cambiosPendientes(raiz: string, rama: string): Promise<CambioLocal[]>;
+/**
+ * Los ficheros del proyecto que git todavía NO sigue (ni en el índice ni ignorados), con su
+ * ruta relativa al PROYECTO.
+ *
+ * Es la otra mitad de «¿falta por subir?» para quien ENSEÑA, no para quien sube:
+ * `cambiosPendientes` es `git diff <ref>` y no ve lo que nadie ha añadido, así que a mitad de
+ * turno —antes del commit del turno— lo que el agente acaba de crear no saldría como pendiente.
+ * `git ls-files` contesta relativo al directorio desde el que se lanza, que es la raíz del
+ * proyecto: no hace falta recortar prefijo. `-z` evita las comillas de rutas con bytes raros.
+ */
+export declare function sinSeguir(raiz: string): Promise<string[]>;
+/** Un fichero pendiente de subir, como se enseña: lo de `FicheroTocado` del cable. */
+export interface FicheroPendiente {
+    ruta: string;
+    clase: "nuevo" | "modificado" | "borrado";
+    mas?: number;
+    menos?: number;
+    /** Git aún no lo sigue: hay que commitearlo antes de poder subirlo. */
+    sinCommitear?: true;
+}
+/**
+ * TODO lo que falta por subir a CloudStudio, como LISTA que enseñar (la pestaña Sincronización
+ * del panel del proyecto): lo que difiere de la ref de la bajada (`cambiosPendientes`, con sus
+ * líneas por `--numstat`) más lo que git aún no sigue (`sinSeguir`), MARCADO `sinCommitear`
+ * porque no se puede subir sin commitearlo y la cifra de la banda no lo cuenta. Esconderlo sería
+ * esconder trabajo nuevo.
+ */
+export declare function pendientesDeSubida(raiz: string, rama: string): Promise<FicheroPendiente[]>;
+/**
+ * El diff de UN fichero pendiente contra lo que consta en CloudStudio (la ref de la bajada), o
+ * contra NADA si git aún no lo sigue. Quien lo llama comprueba antes que la ruta está en la
+ * lista pendiente y que se puede enseñar: aquí solo se pide a git.
+ */
+export declare function parcheDeSubida(raiz: string, rama: string, ruta: string, sinCommitear: boolean): Promise<{
+    texto: string;
+    recortado: boolean;
+} | undefined>;
+/**
+ * «Simular el push»: mover la ref. Solo se llama cuando la subida terminó ENTERA.
+ *
+ * Se mueve la ref de la rama a la que se escribió, que ahora es la MISMA de la que se
+ * bajó (`refs/remotes/cloudstudio/<rama>`), así que «lo que falta por subir» se mide
+ * siempre contra lo último que consta arriba y el libro de cuentas llama a las cosas por
+ * el nombre que tienen en el servidor.
+ */
+export declare function marcarSubido(raiz: string, rama: string, mensaje: string): Promise<void>;
+/**
+ * Mover la ref SOLO por lo que subió: la subida parcial, cuando la persona eligió qué ficheros
+ * subían.
+ *
+ * `marcarSubido` lleva la ref a `HEAD`, y eso afirma «todo lo de esta copia está arriba»: con
+ * una selección sería mentira, y lo que se dejó sin marcar desaparecería de los pendientes sin
+ * haber viajado. Aquí se compone un commit NUEVO cuyo árbol es el de la ref con las rutas
+ * subidas tomadas de `HEAD` (o quitadas, si lo subido era un borrado), y la ref pasa a él. Así
+ * `cambiosPendientes` —que compara la ref contra el árbol— sigue diciendo la verdad: lo no
+ * elegido sigue pendiente.
+ *
+ * Se hace en un índice PRIVADO (`indicePrivado`), como las fotos de `instantanea.ts`: el índice
+ * del usuario no se toca. El commit es hijo de la ref anterior, no de `HEAD`, así que la ref
+ * deja de ser antepasada de `HEAD`; nada lo necesita —la ref solo se usa en `git diff <ref>`,
+ * árbol contra árbol—. Identidad NUESTRA por `-c`, como `commitDeTurno`: sin `user.email`
+ * configurado, `commit-tree` se niega.
+ *
+ * `rutas` son relativas al PROYECTO; git habla desde la raíz del repo, así que se les pone el
+ * prefijo y los comandos corren en la raíz del repo.
+ */
+export declare function marcarSubidoParcial(raiz: string, rama: string, rutas: readonly string[], mensaje: string): Promise<void>;
+/**
+ * ¿Hay cambios sin commitear?
+ *
+ * Lo exigen las DOS direcciones, por motivos distintos: subir sube el estado de un commit
+ * (no un borrador), y bajar SOBRESCRIBE el disco con lo que venga del servidor — sin
+ * commit debajo, el trabajo local no se recupera de ninguna forma.
+ *
+ * `.xonecode/` no cuenta nunca. En el alta, la config del proyecto se escribe ANTES de la
+ * primera descarga y `prepararRepo` (que es quien pone la exclusión en `info/exclude`)
+ * corre DESPUÉS: sin este `:(exclude)`, la propia alta se bloquearía a sí misma en
+ * cualquier repo preexistente. Y la carpeta del harness no sube ni baja jamás.
+ *
+ * **Sin repo** no hay `git status` que valer: se responde por el contenido. Una carpeta
+ * vacía (salvo `.xonecode/` y la basura del sistema operativo) es el alta normal y se deja
+ * pasar; una con ficheros dentro y sin git es justo el caso sin red de seguridad —nada que
+ * recuperar tras sobrescribir—, así que se declara sucia.
+ */
+export declare function arbolLimpio(raiz: string): Promise<boolean>;
+/**
+ * Ficheros que pone el SISTEMA OPERATIVO, no el usuario.
+ *
+ * Sin repo, `sinCommitear` responde por el contenido de la carpeta, y en macOS —la
+ * plataforma de este repo— una carpeta vacía que se ha abierto una vez en el Finder tiene
+ * un `.DS_Store` dentro. Contarlo bloqueaba el alta entera («hay trabajo local sin
+ * commitear (.DS_Store)») sin salida posible desde xonecode, porque `/sync bajar` lleva la
+ * misma guarda: se arreglaba un riesgo real y se rompía el camino feliz.
+ *
+ * Es una LISTA CERRADA y no «ignora los ocultos» a propósito: un `.env` o un `.gitignore`
+ * son trabajo del usuario, y sobrescribirlos sin red de seguridad es exactamente lo que la
+ * guarda existe para impedir. Estos tres no son contenido de ningún proyecto y aparecen
+ * solo por abrir la carpeta.
+ */
+export declare const BASURA_DEL_SO: readonly [".DS_Store", "Thumbs.db", "desktop.ini"];
+/**
+ * QUÉ está sin commitear, para poder decirlo. Es la misma pregunta que `arbolLimpio`
+ * —de hecho aquélla se responde con ésta, para que no haya dos criterios de «limpio»—,
+ * y no la misma que `cambiosPendientes`: aquélla es «qué falta por SUBIR» (diff contra la
+ * ref de seguimiento) y ésta es «qué falta por COMMITEAR».
+ */
+export declare function sinCommitear(raiz: string): Promise<string[]>;
+/** Qué pasó al intentar commitear el turno. No hay excepción: esto lo llama el `finally`
+ *  del turno, y una excepción ahí se llevaría el cierre del turno por delante. */
+export type ResultadoDeCommit = {
+    via: "commit";
+    ficheros: number;
+}
+/** No había nada que commitear: un turno de conversación no toca el disco. */
+ | {
+    via: "sin-cambios";
+}
+/** La carpeta no es un repo. Es la respuesta NORMAL en un proyecto offline. */
+ | {
+    via: "sin-git";
+} | {
+    via: "fallo";
+    motivo: string;
+};
+/**
+ * El trabajo de un turno, commiteado en la rama.
+ *
+ * Existe porque sin él nada se commitea nunca: `prepararRepo` hace UN commit de baseline al
+ * descargar y ahí se acaba, así que el árbol se ensucia y no se limpia jamás. Dos
+ * consecuencias, y la segunda es la que aprieta: las sesiones se mezclan sin que nada pueda
+ * atribuir ni revertir lo de cada una, y **`/sync subir` se vuelve inalcanzable** — su guarda
+ * exige árbol limpio, así que después de cualquier trabajo del agente se niega para siempre.
+ *
+ * Cuatro decisiones:
+ * - **Con el índice DE VERDAD, no con el privado de `arbolDeAhora`.** Aquél existe para una
+ *   foto de solo lectura que no puede tocar el staging del usuario; esto es lo contrario. Si
+ *   el índice no queda igualado con el commit, `git status` enseña reversiones fantasma y
+ *   `trabajoSinCommitear` reporta suciedad que no existe.
+ * - **`.xonecode/` fuera**, con el `rm --cached` de siempre y no con un pathspec de
+ *   exclusión: `git add` con `:(exclude).xonecode` en un repo donde ya está ignorado avisa y
+ *   **sale con código 1** (medido, ver `arbolDeAhora`).
+ * - **Sin cambios no se commitea**, y no es higiene: `git commit` con el índice vacío sale
+ *   con error, así que el camino MÁS común —un turno de conversación— sería un fallo tragado.
+ * - **La identidad es NUESTRA y va por `-c`**, como la del baseline: el commit lo hizo el
+ *   harness, no la persona, y por `-c` no se le escribe nada al `config` de su repo.
+ *
+ * Lo que el mensaje NO puede decir es «lo escribió el agente»: esto barre todo lo que haya
+ * cambiado, incluido lo que tocara una persona a mano en esa carpeta durante el turno. Es la
+ * misma honestidad que separa `autorizadas` de «aplicados».
+ */
+export declare function commitDeTurno(raiz: string, mensaje: string, sesion?: string): Promise<ResultadoDeCommit>;
+/** Cómo se ha respondido, para que nadie afirme lo que no se ha podido mirar. */
+export interface TrabajoSinCommitear {
+    /** `git` = se ha preguntado a git y la lista es la respuesta (vacía = limpio, y eso SE
+     *  SABE). `sin-git` = no hay con qué mirar, y entonces no viene lista: ni sucio ni
+     *  limpio. Es el mismo reparto de `CambiosDeSesion.via` y por el mismo motivo. */
+    via: "git" | "sin-git";
+    ficheros?: string[];
+}
+/**
+ * ¿Había trabajo de alguien sin commitear cuando llegaste? La misma medida que
+ * `sinCommitear` —mismo `git status`, misma exclusión de `.xonecode/`, mismo
+ * `core.quotePath`— con OTRA política ante lo que no se puede mirar, porque la pregunta
+ * es otra.
+ *
+ * `sinCommitear` sostiene una guarda: sin git no hay nada que recuperar tras sobrescribir,
+ * así que declara la carpeta sucia y bloquea, y un git roto LANZA para que `/sync` pare.
+ * Esto sostiene un AVISO, y un aviso que no se puede sostener no se da: sin repo, o con un
+ * git que revienta, se responde `sin-git` y arriba no se pinta nada. Todo proyecto OFFLINE
+ * es una carpeta sin git —`prepararRepo` solo corre al descargar—, así que la política de
+ * la otra pondría un aviso en cada apertura de cada proyecto offline: el aviso que enseña
+ * a ignorar los avisos.
+ *
+ * No lanza NUNCA: de esto cuelga el mensaje de alta de la consola web, que se emite en los
+ * dos flancos de cada turno.
+ */
+export declare function trabajoSinCommitear(raiz: string): Promise<TrabajoSinCommitear>;

package/dist/agent/sesiones/memoriaDeHilo.d.ts

@@ -0,0 +1,4 @@
+/** ¿Queda memoria de esta sesión que continuar? La de cualquiera de los dos motores. */
+export declare function hayMemoriaDeHilo(raiz: string, hilo: string): Promise<boolean>;
+/** Olvida la memoria de esta sesión en los DOS sitios: una sesión borrada no deja conversación en disco. */
+export declare function olvidarMemoriaDeHilo(raiz: string, hilo: string): Promise<void>;

package/dist/agent/sesiones/modeloDelCambio.d.ts

@@ -0,0 +1,7 @@
+import { type CambiosDeUnaColeccion } from "../../core/diffDeColecciones.js";
+/**
+ * Los cambios del modelo de un fichero de la sesión, o `undefined` si no hay «antes» que usar
+ * (una sesión sin marca) o no se pudo reconstruir. Un fichero que no es `.xne` no tiene modelo
+ * que comparar: lista vacía, sin gastar un `git archive`.
+ */
+export declare function modeloDelCambio(raiz: string, sesion: string, ruta: string): Promise<CambiosDeUnaColeccion[] | undefined>;

package/dist/agent/sesiones/parcheEnTexto.d.ts

@@ -0,0 +1,9 @@
+import { type Tabla8Bits } from "../../core/codificacion.js";
+/**
+ * La tabla de 8 bits de un fichero del proyecto, por su prólogo (`tablaDeLosBytes`). Si no se puede
+ * leer —un fichero borrado, cuyo diff solo tiene el ANTES—, windows-1252, que es la omisión de la
+ * misma regla. Solo se lee la cabeza: el prólogo es lo único que decide.
+ */
+export declare function tablaDelFichero(raiz: string, ruta: string): Tabla8Bits;
+/** El diff de git de UN fichero, en bytes, → texto, con la codificación de ESE fichero. */
+export declare function parcheEnTexto(bytes: Uint8Array, raiz: string, ruta: string): string;

package/dist/agent/sesiones/sesionGit.d.ts

@@ -0,0 +1,155 @@
+import type { Cambio } from "../turno/instantanea.js";
+export interface FicheroDeSesion extends Cambio {
+    /** Líneas añadidas y quitadas. `undefined` en un binario: git escribe «-» y fingir un
+     *  cero sería decir que no cambió nada. */
+    mas?: number;
+    menos?: number;
+    /**
+     * Hay cambios en este fichero que NADIE ha commiteado todavía, así que no se pueden
+     * atribuir a esta sesión ni a otra. Se enseñan igual —el turno en vuelo commitea al
+     * TERMINAR, y sin esto la pestaña se quedaría en blanco justo mientras el agente
+     * escribe— pero dichos por lo que son. Ausente = todo lo de esta fila está commiteado.
+     */
+    sinCommitear?: true;
+}
+/** Cómo se ha calculado, para que la interfaz no afirme lo que no sabe. */
+export interface CambiosDeSesion {
+    /**
+     * - `git` = **atribuido por COMMIT**: la lista sale de los commits sellados con el id de
+     *   esta sesión, así que es lo que hizo ESTA sesión y no lo que haya cambiado en la copia
+     *   mientras estaba abierta.
+     * - `desde-apertura` = la sesión no tiene ningún commit sellado (las de antes de que el
+     *   sello existiera, o una cuyo commit falló), así que lo único que se puede medir es el
+     *   árbol de ahora contra la foto de apertura. **Eso NO es atribución** y hay que decirlo
+     *   con otras palabras: ahí dentro está lo que haya escrito cualquiera desde que te
+     *   sentaste. Es la medida que tenía `git` hasta el 10-09-2026, con el nombre corregido —
+     *   dejarle el nombre viejo habría hecho que `revisionConGit` siguiera afirmando una
+     *   autoría que ya se sabe falsa, sin tocar una línea.
+     * - `sin-marca` = no hay con qué mirar: sin git usable, o sesión abierta antes de que
+     *   esto existiera y sin ref.
+     */
+    via: "git" | "desde-apertura" | "sin-marca";
+    ficheros: FicheroDeSesion[];
+    /**
+     * Cuántos commits de OTRAS sesiones caen entre el primero y el último de esta. Solo con
+     * atribución por commit, y solo si hay alguno: la LISTA sigue siendo exacta (se construye
+     * commit a commit), pero el parche de un fichero que dos sesiones se turnaron puede traer
+     * hunks del otro — y eso se dice en vez de fingir aislamiento. Ausente = no se pudo medir
+     * o no hay ninguno.
+     */
+    mezclados?: number;
+}
+/**
+ * El nombre de la ref de una sesión. El id se cuela en un nombre de referencia, así que se
+ * acota a lo que git admite sin ambigüedad —letras, cifras, guion, guion bajo y punto— en
+ * vez de confiar en que quien llama traiga algo limpio: un id con `..`, con un espacio o
+ * empezando por guion no da un error claro, da un `update-ref` que falla raro o, peor, otra
+ * ref.
+ */
+export declare function refDeSesion(id: string): string | undefined;
+/**
+ * La clave del sello que `commitDeTurno` escribe en el mensaje y que esta vista lee.
+ *
+ * Es un TRAILER y no el asunto: el asunto lleva el título de la sesión, que no identifica
+ * nada —dos sesiones se llaman «Hola» en el proyecto del usuario ahora mismo— y que además
+ * cambia si alguien la renombra. El id sí es estable, y un trailer es el sitio que git tiene
+ * para esto: se lee con `%(trailers:key=…)` sin adivinar formato.
+ *
+ * Vive en este módulo, que es el que lo GREPEA, y `gitSync.ts` lo importa para escribirlo:
+ * con el formato en los dos lados, un cambio en uno rompe la atribución del otro en silencio.
+ */
+export declare const CLAVE_DE_SELLO = "Xonecode-Sesion";
+/** El sello de una sesión, listo para pegar al final de un mensaje de commit. */
+export declare function selloDeSesion(id: string): string | undefined;
+/**
+ * Los commits de una sesión, del más VIEJO al más nuevo, y opcionalmente solo los que tocan
+ * una ruta.
+ *
+ * Dos cosas que no son opcionales:
+ * - **`--fixed-strings`**: `--grep` es una expresión regular por omisión, y un id lleva
+ *   puntos y guiones. Aquí no hay daño posible con un uuid, pero el id llega de fuera de
+ *   esta función.
+ * - **Y el `--grep` NO decide: verifica el TRAILER.** Un grep de texto casa por SUBCADENA,
+ *   así que el id `abc` casaría con el sello de `abc1` — o con un id citado dentro del
+ *   cuerpo del mensaje. Se pide el valor del trailer con `%(trailers:key=…,valueonly)` y se
+ *   compara ENTERO. Es exactamente la misatribución silenciosa que esto viene a quitar.
+ *
+ * Exportada (Task 9, IXCODE-11): `web/servidor/datosDeCierre.ts` la usa para los hashes del
+ * comentario de cierre de una tarea — la MISMA lista que ya sostiene `cambiosDeSesion`, así
+ * que no se recalcula con otro criterio.
+ */
+export declare function commitsDeSesion(raiz: string, id: string, ruta?: string): Promise<string[]>;
+/**
+ * La clase NETA de un fichero al que la sesión tocó en varios commits, de la primera vez a
+ * la última. Pura y aparte porque es una decisión, no un detalle del bucle:
+ *
+ * - creado y luego borrado por la misma sesión → **nada**: no estaba antes y no está ahora,
+ *   así que una fila de «borrado» afirmaría que la sesión borró algo que nunca existió.
+ * - lo último es un borrado → borrado.
+ * - lo primero es un alta → nuevo (aunque después lo modificara).
+ * - en cualquier otro caso → modificado.
+ */
+export declare function claseNeta(primera: Cambio["clase"], ultima: Cambio["clase"]): Cambio["clase"] | undefined;
+/**
+ * Marca el ANTES de una sesión. Se llama al abrirla, no al primer turno: lo que interesa es
+ * lo que ha cambiado desde que te sentaste.
+ *
+ * No lanza. Un proyecto sin git usable —o con un hook que revienta— no puede impedir abrir
+ * una sesión; lo que pasa es que después no habrá «antes» que enseñar, y eso se dice con
+ * `via: "sin-marca"` en vez de con una lista vacía que parecería «no tocaste nada».
+ */
+export declare function marcarSesion(raiz: string, id: string): Promise<boolean>;
+/**
+ * La foto se toma AHORA y se nombra DESPUÉS.
+ *
+ * Hace falta porque el id de sesión no existe hasta que se vuelca el primer acto —y para
+ * entonces el agente ya ha escrito—, mientras que el «antes» tiene que ser el momento en que
+ * se abrió el proyecto. Así que se escribe el árbol al abrir y se apunta la ref cuando hay a
+ * qué nombre apuntarla.
+ *
+ * No lanza: un proyecto sin git usable no puede impedir abrir una sesión. Lo que pasa es que
+ * después no habrá «antes» que enseñar, y eso se dice con `via: "sin-marca"` en vez de con
+ * una lista vacía que parecería «no tocaste nada».
+ */
+export declare function fotoDeApertura(raiz: string): Promise<(id: string) => Promise<boolean>>;
+/**
+ * Lo que ha cambiado ESTA sesión.
+ *
+ * **Se atribuye por COMMIT**, que es lo único que dice de quién es cada cambio: cada turno
+ * commitea (`gitSync.ts#commitDeTurno`) con el id de la sesión sellado en el mensaje. La
+ * medida vieja —el árbol de ahora contra la foto de apertura— no atribuía nada, y desde que
+ * hay tareas de fondo escribiendo en la misma copia dejó de ser un proxy razonable: MEDIDO
+ * en el proyecto del usuario el 10-09-2026, una conversación enseñaba +1266 líneas que
+ * había escrito una tarea de fondo veinte minutos después, con la pestaña rotulada
+ * «Sesión». Se conserva como respaldo declarado (`via: "desde-apertura"`) para las sesiones
+ * sin sello, que son todas las de antes de esto.
+ *
+ * Y lo que la atribución por commit NO puede prometer, porque `commitDeTurno` hace `add -A`:
+ * un commit barre todo lo que estuviera sucio en ese instante, incluido lo que tocara otra
+ * sesión sin commitear. Es la misma honestidad que separa `Tarea.autorizadas` de
+ * «aplicados»; el aislamiento de verdad es un árbol por sesión, que no está hecho.
+ */
+export declare function cambiosDeSesion(raiz: string, id: string): Promise<CambiosDeSesion>;
+/**
+ * El parche de UN fichero de la sesión, en texto de git.
+ *
+ * La ruta se pasa después de `--`, que es lo que impide que una ruta que empiece por guion
+ * se lea como una opción. Y se acota el tamaño: la vista no puede pintar un fichero
+ * generado de tres megas, y truncar diciéndolo es mejor que colgar el navegador.
+ */
+export declare function parcheDeSesion(raiz: string, id: string, ruta: string): Promise<{
+    texto: string;
+    recortado: boolean;
+} | undefined>;
+/**
+ * El «antes» de UN fichero en Revisión —el mismo extremo que su parche—, para quien quiera
+ * reconstruir ese estado (el diff semántico de colecciones, `modeloDelCambio.ts`). `undefined`
+ * = no hay «antes» que usar. Devuelve también si es el árbol VACÍO, que no hace falta sacar.
+ */
+export declare function antesDelFichero(raiz: string, id: string, ruta: string): Promise<{
+    ref: string;
+    vacio: boolean;
+} | undefined>;
+/** Olvida la marca de una sesión. Para cuando se borre una sesión: una ref que apunta a un
+ *  árbol de un proyecto que ya no interesa mantiene vivo ese árbol para siempre. */
+export declare function olvidarSesion(raiz: string, id: string): Promise<void>;