xonecode 0.38.41 → 0.39.2

package/dist/core/skills.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Una skill: el `SKILL.md` que el agente carga bajo demanda, y de quién es.
+ *
+ * **Este módulo es PURO.** Quién lee el disco es `agent/grafo/skills.ts`; quién las monta
+ * para el agente, `agent/grafo/proyecto.ts#backendConSkills`. Aquí solo vive el formato del
+ * fichero y la regla de qué nombre vale — las dos cosas que la ventana de Ajustes, el
+ * cargador y los tests tienen que entender igual.
+ *
+ * **Tres orígenes y no dos**, con la misma precedencia que los subagentes y los modelos:
+ *
+ * | origen | dónde | quién la escribe |
+ * |---|---|---|
+ * | `serie` | la carpeta `skills/` del PAQUETE | xonecode, y no se toca desde la consola |
+ * | `global` | `~/.xonecode/skills/` | el usuario, para todos sus proyectos |
+ * | `proyecto` | `<raiz>/.xonecode/skills/` | el usuario, solo para ese proyecto |
+ *
+ * Las de serie son de SOLO LECTURA y no se borran ni se editan: viven dentro del paquete
+ * instalado, así que una edición se la llevaría por delante el siguiente `npm install` sin
+ * decir nada. Lo que sí se puede es COPIARLA a las tuyas y cambiarla ahí, que además deja
+ * ver de dónde salió. Por eso no hay `.semilla.json` como en los subagentes: nada nuestro
+ * se copia nunca a la casa del usuario, así que no hay marca que llevar ni nada que
+ * restaurar.
+ *
+ * El `SKILL.md` es el formato de Claude Code, y eso no es una coincidencia que convenga
+ * mantener: es lo que hace que una skill escrita para otro harness se lea aquí tal cual, y
+ * que `SkillsMiddleware` de deepagents —que es quien las descubre de verdad— la encuentre
+ * sin que xonecode traduzca nada.
+ */
+import { motivoDeNombreInaceptable, nombreSugerido } from "./agentes.js";
+/** De dónde sale una skill. No se escribe en el fichero: lo pone quien lo lee. */
+export type OrigenDeSkill = "serie" | "global" | "proyecto";
+/** El fichero, sin de quién es. Es lo que se escribe y lo que se lee. */
+export interface Skill {
+    nombre: string;
+    descripcion: string;
+    /** El cuerpo del `SKILL.md`, sin el frontmatter. Son las instrucciones. */
+    cuerpo: string;
+    /**
+     * El frontmatter TAL COMO está en el fichero, sin los `---`.
+     *
+     * Existe por dos cosas distintas y las dos importan:
+     *
+     * - **Se ENSEÑA.** `description` no es lo único que puede haber ahí: `archify` declara
+     *   además `license` y un bloque `metadata` anidado, y una ventana que solo enseña la
+     *   descripción haría creer que eso es todo lo que el fichero dice.
+     * - **Se CONSERVA al guardar.** `escribirSkill` reescribe `name` y `description` DENTRO de
+     *   este texto en vez de componer uno nuevo: sin eso, editar desde la ventana una skill
+     *   escrita a mano le borraba en silencio todas las claves que no conocemos — que es la
+     *   pérdida muda de siempre, y encima sobre un fichero que el usuario escribió él.
+     *
+     * Ausente en la que se está creando: entonces se compone el mínimo.
+     */
+    frontmatter?: string;
+}
+/** Una skill ya cargada: el fichero, más de dónde salió y lo que cuesta. */
+export interface SkillCargada extends Skill {
+    origen: OrigenDeSkill;
+    /** Estimación de coste del `SKILL.md` ENTERO, frontmatter incluido. */
+    tokens: number;
+    /**
+     * Los ficheros que acompañan al `SKILL.md`, por nombre y sin contenido.
+     *
+     * Viajan porque una skill puede ser una carpeta entera —plantillas, ejemplos, un script—
+     * y la ventana que solo enseña el `SKILL.md` haría creer que editarlo es editarla toda.
+     * Lo que se puede tocar desde aquí es el `SKILL.md`; el resto se dice que está y se deja
+     * donde vive, que es la misma postura que `omitidas` en el plan de subida.
+     */
+    ficheros: string[];
+}
+/** Lo que se pudo leer, y lo que no con su motivo. Nunca se descarta nada en silencio. */
+export interface LecturaDeSkills {
+    skills: SkillCargada[];
+    /** Una línea por fichero: qué skill y qué le pasa. */
+    problemas: string[];
+}
+/** 4 caracteres por token, la regla de servilleta de siempre. */
+export declare const tokensDeSkill: (texto: string) => number;
+/**
+ * El nombre de una skill es un SEGMENTO DE RUTA —la carpeta donde vive— y también lo que el
+ * subagente declara en su `.md`, así que vale la MISMA regla que la de un subagente y por la
+ * misma razón: `motivoDeNombreInaceptable` (`core/agentes.ts`). No se escribe una segunda
+ * aquí porque dos reglas para el mismo tipo de nombre es donde divergen.
+ */
+export declare const motivoDeNombreDeSkillInaceptable: typeof motivoDeNombreInaceptable;
+export declare const nombreDeSkillSugerido: typeof nombreSugerido;
+/**
+ * Compone el `SKILL.md`.
+ *
+ * El frontmatter es el mínimo que `parseFrontmatter` (`vendor/skillLoaders/catalog.ts`) y
+ * deepagents leen: `name` y `description`, una línea cada uno. La descripción se aplana a
+ * una línea porque ahí un salto la partiría en dos claves y la segunda mitad se perdería en
+ * silencio — el mismo motivo por el que el nombre es un slug.
+ *
+ * **Y lo demás del frontmatter se CONSERVA**: las claves que no son `name` ni `description`
+ * se reescriben tal cual, en su orden. Componer uno nuevo desde cero le borraba a una skill
+ * escrita a mano su `license`, su `allowed-tools` o su bloque `metadata` en cuanto alguien
+ * abriera la ventana y pulsara Guardar — sin error, sin aviso y sobre un fichero suyo. Las
+ * líneas INDENTADAS van con la clave que las abre, que es lo que deja pasar un bloque
+ * anidado entero sin entender YAML.
+ */
+export declare function escribirSkill(skill: Skill): string;
+/**
+ * Lee un `SKILL.md`.
+ *
+ * **El nombre sale de la CARPETA, no del frontmatter**, exactamente como el de un subagente
+ * sale del fichero: es lo que la hace direccionable (`/skills/<nombre>/`) y lo que el
+ * subagente declara. Un `name:` que diga otra cosa se ignora — mandaría sobre una ruta que
+ * ya está decidida, y entonces `rutasDeSkills` apuntaría a una carpeta que no existe.
+ *
+ * **Sin `description` no se carga.** Es lo que el modelo lee para decidir si esta skill le
+ * sirve: sin ella, la skill está en el catálogo y no la usa nadie nunca, que es peor que no
+ * estar. Misma regla que la `descripcion` de un subagente.
+ */
+export declare function leerSkill(texto: string, nombreDeCarpeta: string, origen: OrigenDeSkill, ficheros?: string[]): {
+    skill: SkillCargada;
+} | {
+    error: string;
+};
+/**
+ * Funde las listas por nombre: la ÚLTIMA gana.
+ *
+ * Se llama con `serie`, `global`, `proyecto` en ese orden, así que una skill del proyecto
+ * tapa a la global del mismo nombre y las dos tapan a la de serie — la misma precedencia
+ * que los subagentes y que los modelos, y por lo mismo: lo particular manda sobre lo
+ * general. Que una tape a otra NO es un problema que reportar: es la forma de afinar una
+ * skill nuestra sin editarla donde el `npm install` la pisaría. Quien lo dice es la ficha,
+ * con su origen al lado.
+ */
+export declare function fusionarSkills(...listas: readonly SkillCargada[][]): SkillCargada[];

package/dist/core/stitch.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Traer una pantalla de Stitch a la sesión: lo que se decide sin red ni disco.
+ *
+ * Stitch no devuelve la imagen ni el HTML de una pantalla: devuelve ENLACES de descarga
+ * (`get_screen` → `screenshot.downloadUrl`, `htmlCode.downloadUrl`), y el agente no puede bajar
+ * una URL. Lo baja el harness (`agent/motores/trueforge/traerDeStitch.ts`), y solo URLs que vienen
+ * de la respuesta de Stitch —nunca una que escriba el modelo—, de los hosts MEDIDOS, con tope de
+ * tamaño y tipo comprobado.
+ *
+ * El destino es FIJO, `/artefactos/diseno/`: es donde el harness ya espera una maqueta (`buscarMaqueta`),
+ * de donde `ultimaCaptura` y el crítico de pantalla NO toman capturas del aparato, y la misma carpeta
+ * que deja descomprimir un export de Stitch a mano.
+ */
+import type { DisenoVinculado } from "./disenoVinculado.js";
+export { motivoDeProyectoDeStitchInaceptable, type DisenoVinculado } from "./disenoVinculado.js";
+/** La carpeta, dentro de la de artefactos, donde vive la maqueta traída. */
+export declare const CARPETA_DE_DISENO = "diseno";
+export declare const RUTA_DE_DISENO = "/artefactos/diseno/";
+/** ¿Es esta ruta virtual algo de la maqueta traída (y no una captura del aparato)? */
+export declare function esDeLaMaqueta(ruta: string): boolean;
+/** Medidos el 30-09-2026: la imagen viene de `lh3`, el HTML de `contribution`. Nada más se baja. */
+export declare const HOSTS_DE_DESCARGA: readonly ["lh3.googleusercontent.com", "contribution.usercontent.google.com"];
+/** Una pantalla de Stitch a tamaño completo son ~150 KB; el tope es holgado y es un tope. */
+export declare const TOPE_DE_IMAGEN: number;
+export declare const TOPE_DE_HTML: number;
+/** Lo que admite la imagen: el tipo manda sobre la extensión del fichero que se escribe. */
+export declare const TIPOS_DE_IMAGEN: Readonly<Record<string, string>>;
+export declare function motivoDePantallaInaceptable(pantalla: string): string | undefined;
+/** El proyecto de una pantalla: `projects/<id>`. */
+export declare function proyectoDePantalla(pantalla: string): string;
+/**
+ * ¿Se puede bajar esta URL? HTTPS, sin credenciales, de un host medido. Se aplica a URLs que vienen
+ * de la respuesta de Stitch, y aun así se comprueba: la respuesta la escribe otro.
+ */
+export declare function motivoDeDescargaInaceptable(url: string): string | undefined;
+/**
+ * La imagen a su tamaño REAL. Medido: el enlace de `lh3` sin sufijo da una miniatura (226×512 de una
+ * pantalla de 780×1768); con `=s0`, la de verdad. Solo si el enlace no trae ya su propio tamaño.
+ */
+export declare function urlDeImagenCompleta(url: string): string;
+export interface PantallaDeStitch {
+    titulo: string;
+    ancho?: number;
+    alto?: number;
+    imagen: string;
+    html?: string;
+}
+/** Lo que interesa de la respuesta de `get_screen`, o el motivo de que no se entienda. */
+export declare function leerPantalla(texto: string): PantallaDeStitch | string;
+/** El `DESIGN.md` del proyecto (`get_project` → `designTheme.designMd`), si lo trae. */
+export declare function designMdDeProyecto(texto: string): string | undefined;
+/**
+ * Buscar una pantalla por su TÍTULO, y no por su `name`. Medido en Maset: con solo el `name`, el orquestador listaba las
+ * pantallas de TODOS los proyectos de Stitch (diecinueve llamadas) para dar con la que la persona había nombrado, y esos
+ * listados se quedaban en su contexto el turno entero. Puro: las respuestas entran como texto.
+ */
+export interface EntradaDeStitch {
+    name: string;
+    title: string;
+}
+/** Un título comparable: sin mayúsculas, sin tildes y con los espacios reducidos. */
+export declare function tituloComparable(titulo: string): string;
+/** Las entradas `{name, title}` de la lista `clave` (`projects` o `screens`) de una respuesta. Lo que no tiene forma, fuera. */
+export declare function entradasDeStitch(texto: string, clave: "projects" | "screens"): EntradaDeStitch[];
+/**
+ * Las que casan con el título: las de título IGUAL si hay alguna (comparable), y si no las que lo CONTIENEN. Sin título,
+ * todas. Una pantalla con el título exacto no se ensucia con las que solo lo contienen.
+ */
+export declare function casanConTitulo<T extends EntradaDeStitch>(entradas: readonly T[], titulo: string | undefined): T[];
+/**
+ * Las palabras de un título, comparables y por su RAÍZ, sin las vacías: singular y plural valen lo mismo (`entregas` y
+ * `entrega`, `albaranes` y `albaran`, `pendientes` y `pendiente`). Se quita `-es`/`-s` y luego una `e` final.
+ */
+export declare function palabras(titulo: string): string[];
+/**
+ * Las palabras de lo buscado que DISTINGUEN una pantalla de otra: sin las vacías y sin las que salen en la MAYORÍA de
+ * los títulos del proyecto («Maset», «Logística» en «X - Maset Logística»), que no distinguen nada.
+ */
+export declare function palabrasQueDistinguen(titulo: string, entradas: readonly EntradaDeStitch[]): string[];
+/** El id de un proyecto (`projects/<id>` → `<id>`), que es lo que pide `list_screens`. */
+export declare function idDeProyecto(name: string): string;
+/** Una pantalla para el selector: su `name`, su título y la miniatura (solo de los hosts medidos). */
+export interface PantallaConMiniatura extends EntradaDeStitch {
+    miniatura?: string;
+}
+/**
+ * Las pantallas de una respuesta de `list_screens`, con su miniatura (`screenshot.downloadUrl`, medido: la traen todas).
+ * Una miniatura fuera de los hosts medidos no se da: la pantalla se ofrece sin imagen.
+ */
+export declare function pantallasConMiniatura(texto: string): PantallaConMiniatura[];
+/**
+ * La pantalla elegida para una tarea, si vale: un `name` de pantalla bien formado, DEL proyecto de Stitch vinculado, y
+ * un título corto. Lo que llega del cable no se cree: sin vínculo, o de otro proyecto, `undefined`.
+ */
+export declare function pantallaElegidaValida(valor: unknown, vinculo: DisenoVinculado | undefined): {
+    name: string;
+    titulo: string;
+    proyecto: string;
+} | undefined;
+/**
+ * La línea que se añade al encargo de una tarea con pantalla ELEGIDA: si ya está traída, dónde está y que es LA
+ * referencia; si no se pudo traer antes de empezar, con qué `name` traerla. En los dos casos, que no se busque otra por
+ * título ni se sustituya (decisión suya: el diseño lo elige la persona).
+ */
+export declare function textoDePantallaElegida(pantalla: {
+    name: string;
+    titulo: string;
+    proyecto?: string;
+}, traida: {
+    ok: true;
+} | {
+    ok: false;
+    motivo: string;
+}): string;

package/dist/core/tareas.d.ts

@@ -0,0 +1,412 @@
+import type { CierreDeTarea, VeredictoDeTarea } from "./entrega.js";
+import type { MapeoDeEstados } from "./gestorDeTareas.js";
+/**
+ * Los cuatro estados, y ninguno más.
+ *
+ * **No hay «fallida»**: un error del turno, un proyecto que ya no está, una escritura que
+ * nadie aprobó y una pregunta sin contestar acaban todos en `requiere-atencion`, porque la
+ * acción que piden es la misma —que alguien mire— y lo que los distingue es el `motivo`. Un
+ * estado «fallida» aparte obligaría a decidir en el código qué fallos son recuperables, y
+ * esa es justo la decisión que se le devuelve a la persona.
+ *
+ * **Tampoco hay «cancelada»**: descartar una tarea la BORRA. Un estado terminal de basura
+ * sería un archivo que nadie mira, la misma razón por la que «archivar» no está en el menú
+ * de una sesión.
+ */
+export type EstadoDeTarea = "nuevo" | "en-proceso" | "requiere-atencion" | "terminada";
+/** A dónde se puede ir desde cada estado. Lo que no esté aquí se rechaza al escribirlo. */
+export declare const TRANSICIONES: Readonly<Record<EstadoDeTarea, readonly EstadoDeTarea[]>>;
+/** Lo que se sabe de un adjunto. Nunca su contenido ni su ruta en la máquina. */
+export interface AdjuntoDeTarea {
+    nombre: string;
+    bytes: number;
+    /** Por extensión, o ausente si no se sabe. Nunca se adivina. */
+    mime?: string;
+}
+/**
+ * Un feedback del desarrollador sobre una tarea que estaba `requiere-atencion`.
+ *
+ * §0 del diseño, textual: «esperando por feedback, se edita la tarea y se agrega el
+ * feedback del usuario». Es el mismo patrón que los hallazgos del verificador
+ * (`agent/turno/turnoReal.ts#conVerificacion`): entra al hilo que ya existe como un mensaje de
+ * USUARIO, nunca como un encargo nuevo que le haría perder a la tarea todo lo que ya sabe.
+ */
+export interface FeedbackDeTarea {
+    texto: string;
+    creado: string;
+    /**
+     * Si ya se le mandó al agente. Se pone al REANUDAR el turno con este feedback —no al
+     * añadirlo—, o la vuelta siguiente del corredor se lo mandaría otra vez: el mismo
+     * argumento que separa «autorizó» de «aplicado» en `Tarea.autorizadas`, aquí dentro de
+     * cada entrada en vez de en el campo entero.
+     */
+    consumido: boolean;
+}
+export interface Tarea {
+    id: string;
+    /**
+     * El proyecto, con las TRES cosas y no dos: el `id` es lo que viaja por el cable y con lo
+     * que la interfaz filtra («las tareas de este proyecto»), el `nombre` es para leer, y la
+     * `raiz` es ABSOLUTA y solo se usa aquí dentro para abrirlo.
+     *
+     * Mover o renombrar la carpeta deja la tarea huérfana, y entonces NO se ejecuta — falla
+     * cerrado, igual que el índice de tareas, que también se indexa por ruta absoluta.
+     */
+    proyecto: {
+        id: string;
+        raiz: string;
+        nombre: string;
+    };
+    /** La primera frase de la petición. Para leer en el kanban. */
+    titulo: string;
+    /** Lo que escribió el usuario, tal cual. Se conserva aunque el encargo se edite. */
+    peticion: string;
+    /** El encargo augmentado y revisado: es lo que se le manda al agente. */
+    encargo: string;
+    adjuntos: AdjuntoDeTarea[];
+    estado: EstadoDeTarea;
+    /** Por qué está aparcada. Obligatorio con `requiere-atencion` y solo con él. */
+    motivo?: string;
+    /** La sesión donde corre, en cuanto existe: es lo que hace que atenderla sea abrirla. */
+    sesion?: string;
+    /**
+     * La tarea ANTERIOR de su cadena: esta no arranca hasta que aquella esté `terminada`. Existe porque un encargo grande
+     * se reparte en tareas que van EN ORDEN (`docs/superpowers/plans/2026-10-06-tareas-encadenadas.md`), y la regla de
+     * «nunca dos del mismo proyecto» no basta: deja de bloquear cuando la anterior queda en `requiere-atencion`, y la
+     * siguiente arrancaría sobre un trabajo a medias. Si la anterior ya no existe (la persona la borró), esta queda libre.
+     */
+    tras?: string;
+    creada: string;
+    empezada?: string;
+    acabada?: string;
+    /** El proceso que la tiene. Se usa para reconciliar al arrancar; se va al parar. */
+    pid?: number;
+    /**
+     * Cuántas veces el harness la REANUDÓ solo tras cortarse el proceso a mitad (`reanudadaTrasCorte`). Ausente = ninguna.
+     * Es lo que frena el bucle de una tarea que tumba el proceso cada vez. No viaja: en la pantalla no sirve de nada.
+     */
+    reanudaciones?: number;
+    /**
+     * Las escrituras que la tarea AUTORIZÓ sin que ninguna persona las aprobara, con la ruta
+     * RELATIVA a la raíz del proyecto.
+     *
+     * **Se llama `autorizadas` y no `aplicados`, y el nombre es la mitad del contrato.** Se
+     * apunta cuando se toma la decisión, que es ANTES de que el backend escriba: una ruta que
+     * las guardas de ruta rechazan —`/artifacts/`, una vista aplanada, `/.env`— sale aquí y
+     * NO aparece en el disco. Un campo llamado «aplicados» prometería un hecho sobre el disco
+     * que este dato no puede sostener, y de aquí sale lo que el kanban le cuenta a una
+     * persona: en este repo un campo mal nombrado es la misma clase de fallo que un control
+     * sin dato detrás. **La verdad sobre lo que cambió la tiene Revisión**, que es un diff de
+     * git contra la ref de la sesión; esto es una PISTA, y su nombre no puede prometer más.
+     *
+     * **Se guarda porque nadie lo aprobó.** La autorización de una tarea es el acto de
+     * crearla, así que el diff dejó de ser el momento en que alguien ve lo que se va a
+     * escribir; lo único que queda es el registro. Con los NOMBRES y no un contador, que es
+     * el mismo criterio del aviso de honestidad del modo autónomo — un contador a
+     * secas es el aviso que enseña a ignorar los avisos.
+     *
+     * **Ausente y vacío no son lo mismo**, y aquí la diferencia es la de siempre: ausente es
+     * «no consta» —una tarea de antes de que esto existiera, o una que nunca llegó a correr
+     * un turno porque su proyecto no estaba— y `[]` es «corrió y no autorizó ninguna
+     * escritura», que es un dato distinto y el que el juez de la entrega necesita.
+     */
+    autorizadas?: string[];
+    /**
+     * El historial de lo que el desarrollador contestó mientras la tarea esperaba feedback.
+     *
+     * **Es una LISTA y no un campo**, porque puede haber varias vueltas —una tarea aparcada
+     * dos veces— y la segunda no puede borrar la primera: la misma regla que `autorizadas`.
+     * `conFeedback` solo AÑADE.
+     *
+     * **Ausente y vacío no son lo mismo, otra vez la misma regla.** Ausente es «nunca se le
+     * pidió nada a esta tarea»; `conFeedback` nunca produce `[]` porque solo se llama para
+     * AÑADIR un feedback, así que un array presente siempre tiene al menos uno.
+     */
+    feedback?: FeedbackDeTarea[];
+    /**
+     * El veredicto del juez de QA sobre lo que hizo la tarea: resumen y hallazgos, **nunca
+     * contenido de ficheros** (`core/entrega.ts#VeredictoDeTarea` lo acota).
+     *
+     * Se guarda porque es la mitad de la decisión de «terminada» —la otra son las condiciones
+     * que comprueba el código— y porque cuando el veredicto es el motivo de que la tarea NO
+     * se entregue, sus palabras son lo único que dice qué falta. Se guarda **siempre que haya
+     * uno**, también en verde: si no, una tarea terminada no podría distinguir «el juez la
+     * aprobó» de «se entregó sin que nadie la juzgara», que es la duda que este campo existe
+     * para cerrar. Y la cierra en la PANTALLA, no solo en disco: viaja entero por el cable
+     * (`web/servidor/transporte.ts#filaDeTarea`) y lo pinta `EntregaDeTarea.tsx`. La cuarta
+     * forma de llegar a «terminada» —que la dé por buena una persona— no la puede distinguir
+     * este campo, porque el veredicto que hubiera se conserva: la distingue
+     * `terminadaAMano`.
+     *
+     * **Y este SUSTITUYE, al contrario que `autorizadas`.** Aquello acumula porque un
+     * fichero escrito en el primer intento sigue escrito; un veredicto, en cambio, es una
+     * opinión sobre el estado ACTUAL del trabajo, y conservar el del intento anterior al lado
+     * del nuevo enseñaría dos respuestas a una sola pregunta.
+     */
+    veredicto?: VeredictoDeTarea;
+    /**
+     * Con qué se CERRÓ, cuando la entrega no salió limpia (`core/entrega.ts#cierreDeLaEntrega`): lo crítico y las
+     * observaciones, que van al comentario de cierre del ticket. Ausente = se entregó sin nada que decir.
+     */
+    cierre?: CierreDeTarea;
+    /**
+     * La dio por buena una PERSONA, con el botón «Dar por bueno», en vez de la puerta de
+     * entrega (`core/entrega.ts#decisionDeEntrega`).
+     *
+     * **Existe porque el veredicto no basta para distinguirlo, y eso está razonado sobre el
+     * código y no supuesto.** Una tarea aparcada puede llegar a ese botón con un veredicto
+     * ROJO (el juez dijo que no y la persona lo pisa), con NINGUNO (se cortó a mitad, el turno
+     * falló, el proyecto ya no estaba: el juez no llegó a hablar) y también con uno VERDE —el
+     * camino es estrecho pero existe: la puerta la aprueba y la escritura del estado final
+     * revienta, así que se aparca «el corredor no pudo cerrarla» con el verde ya guardado
+     * (`corredorDeTareas.ts`)—. En ese último caso, sin esta marca, la tarjeta resultante
+     * sería byte a byte la de una entrega por la puerta completa.
+     *
+     * **Solo la pone `darPorBuenaAMano`**, nunca `conEstado`: marcar ahí una entrega del
+     * corredor sería la mentira simétrica. Y `undefined` es «no consta» —una tarea de antes
+     * de que esto existiera—, que no es lo mismo que `false`.
+     */
+    terminadaAMano?: boolean;
+    /**
+     * El ticket del GESTOR de tareas en el que vive esta tarea (Jira, Notion…), si su proyecto tenía uno vinculado al
+     * crearla. Se COPIA al crear y no se recalcula nunca desde el vínculo de ahora —la regla de `TicketDeSesion`—: si la
+     * persona revincula el proyecto, lo que se escribe sigue yendo a ESTE ticket. Ausente = tarea solo local.
+     */
+    ticket?: TicketDeTarea;
+    /**
+     * La pantalla de Stitch ELEGIDA para la tarea (una), del proyecto de Stitch vinculado. El corredor la trae a
+     * `/artefactos/diseno/` antes del primer turno y el encargo lo dice: no se busca por nombre (decisión suya; medido en
+     * Maset, «Menu Listado Entregas» no era el título de ninguna y la tarea construyó con otra maqueta).
+     */
+    pantallaDeStitch?: PantallaElegida;
+}
+/** Una pantalla de Stitch elegida: su `name` (`projects/<id>/screens/<id>`) y su título, para decirlo sin preguntar. */
+export interface PantallaElegida {
+    name: string;
+    titulo: string;
+    /** El nombre del proyecto de Stitch, del vínculo al crearla; su id sale del `name`. */
+    proyecto?: string;
+}
+/** El ticket de una tarea en su gestor. `sitio` no sale del host; `aviso` es el último reflejo que FALLÓ. */
+export interface TicketDeTarea {
+    conector: string;
+    sitio: string;
+    /** El proyecto del gestor (clave de Jira, data source de Notion): lo que el adaptador necesita en el `Vinculo`. */
+    proyecto: string;
+    clave: string;
+    url?: string;
+    /** Lo que no se pudo escribir en el gestor la última vez («no se pudo pasar a PROBAR: …»). Ausente = nada pendiente. */
+    aviso?: string;
+    /** El mapeo de estados del vínculo AL CREARLA (copiado, como el resto): a qué estado pasa al empezar y al terminar. */
+    estados?: MapeoDeEstados;
+}
+/**
+ * La ruta de un fichero tal como se apunta y se dice en una tarea: relativa a la raíz.
+ *
+ * Las rutas que llegan de un interrupt vienen del backend virtual del agente (`/app.xne`),
+ * así que nunca son de la máquina — pero la barra de delante las hace parecerlo, y estas
+ * cadenas acaban en el índice de tareas y en el registro que una persona lee. Vive aquí, y
+ * no en quien las escribe, porque la usan los dos extremos: el texto que se pinta en el
+ * transcript y la lista que se guarda. Dos copias de esto son dos reglas que divergen.
+ */
+export declare const rutaRelativaDeTarea: (ruta: string) => string;
+/** El título de una tarea: la primera frase de su petición, como el de una sesión. */
+export declare const tituloDeTarea: (peticion: string) => string;
+/** Tope de concurrencia por omisión. Dos: una corriendo y otra avanzando sin que la máquina
+ *  se quede sin aire para lo que esté haciendo la persona delante. */
+export declare const CONCURRENCIA_POR_OMISION = 2;
+/**
+ * Cuántas RONDAS de aprobación admite el turno de una tarea. **Su propio tope, y no el de
+ * la persona.**
+ *
+ * `MAX_APPROVAL_ROUNDS` son cinco y se dimensionaron para alguien pulsando: «te lo he
+ * preguntado cinco veces, para». En una tarea autónoma una ronda no es una pregunta, es una
+ * TANDA de escrituras que se autorizan solas — y cinco tandas se agotan en un encargo
+ * mediano: medido, un turno de tarea acabó con cuatro ficheros escritos, una escritura
+ * abandonada y el verificador sin correr, porque cada tanda gastaba ronda.
+ *
+ * **Y no es infinito**, por el mismo argumento que el tope propio de los artefactos: cada
+ * pasada es una llamada al modelo y aquí no hay ningún humano que frene el bucle.
+ *
+ * **De dónde sale el 20, dicho como lo que es: una observación por cuatro, no un encargo
+ * grande medido.** Lo único medido es el turno que se cortó, que necesitaba cinco tandas;
+ * veinte deja sitio a un encargo bastante mayor y sigue cortando un bucle en un tiempo
+ * finito. No hay medida de un encargo de verdad grande detrás, y por eso es un número
+ * provisional que se puede afinar. Lo que lo hace aceptable mientras tanto es su MODO DE
+ * FALLO: al agotarse se dice, quedan escrituras sin aplicar, y `core/entrega.ts` no entrega
+ * — o sea que un tope corto aparca con un motivo VERDADERO en vez de dar por bueno un
+ * trabajo a medias. Un número provisional con un fallo honesto se afina luego; lo que no se
+ * puede es que al agotarse mienta.
+ *
+ * **Subido a 50 por una medida**: una tarea que ajustaba una pantalla contra su maqueta (Maset, Entradas/Salidas) gastó
+ * las 20 en un solo turno —editar, desplegar, capturar, criticar, volver a editar, una edición por fichero y ronda— y se
+ * cortó con tres ediciones sin aplicar y el simulador sin correr, con la ventana casi lista. Ese ciclo de diseño es el
+ * trabajo normal de una tarea, no un bucle; a petición de la persona, el mismo 50 que el chat.
+ */
+export declare const TOPE_DE_RONDAS_DE_TAREA = 50;
+/**
+ * Qué tareas pueden arrancar AHORA.
+ *
+ * Cuatro reglas, y las dos últimas son las que importan:
+ *  - **FIFO por fecha de creación**, global: predecible y explicable. Una prioridad es un
+ *    campo más que nadie ha pedido.
+ *  - **Tope de concurrencia**, contando las que ya corren.
+ *  - **Nunca dos del mismo proyecto**, ni con las que corren ni entre las elegidas en esta
+ *    misma pasada: comparten disco, índice de git, checkpointer y `sync`, y dos turnos a la
+ *    vez sobre eso es una carrera con escrituras de por medio.
+ *  - **Y GANA LA PERSONA**: ver `bloqueados`.
+ *  - **Y las ENCADENADAS esperan a su anterior** (`Tarea.tras`) hasta que esté `terminada`, también si quedó en
+ *    `requiere-atencion`. Igual que un bloqueado: no gasta hueco ni para la cola.
+ */
+export declare function siguientesAEjecutar(tareas: readonly Tarea[], opciones: {
+    concurrencia: number;
+    /**
+     * Raíces en las que NO se puede arrancar nada, aunque haya hueco.
+     *
+     * Existe por el hueco que el cerrojo del corredor no cubre: ese arbitra dos
+     * CORREDORES, y esto es una tarea y una PERSONA sobre el mismo árbol, que no tienen
+     * aislamiento de ninguna clase — se pisan las ediciones, y la foto por turno de
+     * `instantanea.ts` metería las escrituras de la tarea en el diff de la persona,
+     * atribuyéndoselas. Gana la persona: la tarea espera.
+     *
+     * La condición que se le pasa es «la consola está ABIERTA» y no «hay un turno en
+     * vuelo», porque solo la primera es estable en el instante de despachar: con la
+     * segunda, una tarea arrancaría y chocaría después, que es justo el fallo que se
+     * quiere evitar.
+     *
+     * **No gasta hueco de concurrencia** —no está corriendo nada— y **no para la cola**:
+     * el hueco se lo lleva la siguiente de otro proyecto. Ausente y vacía significan lo
+     * mismo aquí (nada que bloquear), al contrario que en `Entorno.proyectos`: no hay
+     * ninguna omisión que una lista vacía pudiera estar contradiciendo.
+     */
+    bloqueados?: readonly string[];
+}): Tarea[];
+/**
+ * La tarea con otro estado, o una excepción.
+ *
+ * Lanza en vez de devolver la tarea sin tocar: un estado imposible escrito en disco es más
+ * difícil de depurar que un error en el momento de escribirlo. Y `requiere-atencion` EXIGE
+ * motivo, porque una tarea aparcada sin decir por qué no es accionable — es la misma razón
+ * por la que el aviso de honestidad lleva los nombres de los ficheros y no un contador.
+ */
+export declare function conEstado(tarea: Tarea, estado: EstadoDeTarea, motivo?: string, sello?: {
+    pid?: number;
+    ahora?: string;
+}): Tarea;
+/**
+ * La tarea con lo que AUTORIZÓ, si es que se sabe.
+ *
+ * `undefined` significa «no se sabe» y entonces no se toca el campo: una tarea que ni
+ * llegó a correr un turno —su proyecto se movió— no autorizó nada, pero afirmarlo con una
+ * lista vacía sería contar como medido algo que nadie midió. Es la misma distinción que
+ * `Entorno.proyectos` y la que `detalles` de un acto guardado conserva.
+ *
+ * **Se SUMA a lo que ya hubiera, no lo sustituye.** Una tarea aparcada se reintenta
+ * (`requiere-atencion → nuevo`) y su segundo turno es otro turno: si esto reemplazara, el
+ * fichero que autorizó el primer intento desaparecería del registro **cuando muy
+ * probablemente siga escrito**, que es justo la clase de mentira que este campo evita. Y así `[]` sigue
+ * queriendo decir lo que dice: «este turno no autorizó nada» — no borra lo que autorizó el
+ * anterior. (`sesion` NO se pierde al reintentar: el corredor reabre la MISMA —Task 12,
+ * `corredorDeTareas.ts#correr`—, así que el segundo turno cae en el mismo hilo y Revisión
+ * sigue comparando contra el «antes» de la primera apertura, no contra uno a medias.)
+ *
+ * Normaliza en un solo sitio: rutas relativas (`rutaRelativaDeTarea`), sin huecos y sin
+ * repetidos — el mismo fichero escrito en dos rondas del turno, o en dos intentos, es un
+ * fichero tocado y no dos—, conservando el orden en que se aplicaron.
+ */
+export declare function conAutorizadas(tarea: Tarea, autorizadas: readonly string[] | undefined): Tarea;
+/**
+ * La tarea con un feedback nuevo, sin consumir, y devuelta al lazo (`requiere-atencion →
+ * nuevo`).
+ *
+ * **Rechaza el vacío, lanzando.** Un feedback en blanco devolvería la tarea al lazo sin
+ * nada nuevo que decirle: la aparcaron por una decisión que hacía falta tomar, y «nada» no
+ * es una decisión. Es el mismo argumento que rechaza un título vacío en
+ * `sesiones.ts#renombrarSesion` — no es validación de formulario, es que aceptarlo dejaría
+ * la tarea «resuelta» sin haberla resuelto, y el siguiente turno correría igual de
+ * bloqueado que este.
+ *
+ * **Solo vale desde `requiere-atencion`, y eso lo decide `conEstado` y no una comprobación
+ * aparte aquí.** Si la tarea no está aparcada, no hay pregunta que este feedback esté
+ * contestando; `conEstado` ya lanza con un motivo legible (`«nuevo» no puede pasar a
+ * «nuevo»`), y repetir esa regla en dos sitios es como acaban divergiendo.
+ *
+ * **Se SUMA a lo que ya hubiera, nunca lo sustituye** — la misma regla que
+ * `conAutorizadas`: un segundo feedback no puede borrar el primero, porque el agente ya
+ * actuó sobre lo que el primero dijo y perder el registro sería fingir que nunca se dijo.
+ * `consumido` nace en `false`: se pone en `true` cuando el corredor de verdad lo manda al
+ * turno (`corredorDeTareas.ts#correr`), no aquí — hasta entonces «no consta que se haya
+ * mandado» es la verdad.
+ */
+export declare function conFeedback(tarea: Tarea, texto: string, ahora?: string): Tarea;
+/**
+ * ¿Se puede cambiar su encargo? (IXCODE-52). Solo una que NUNCA ha arrancado: `nuevo` y sin
+ * `empezada`. Una reintentada o con feedback también vuelve a `nuevo`, pero lo que se le manda
+ * entonces es su hilo y el feedback, no el encargo: dejar editarlo sería cambiar un texto que el
+ * agente no va a volver a leer.
+ */
+export declare function puedeEditarEncargo(tarea: Pick<Tarea, "estado" | "empezada">): boolean;
+/**
+ * La tarea con otro encargo, o una excepción con el motivo. Sin `peticion`, la petición y el título
+ * no se tocan; con ella (IXCODE-53: se edita lo que escribió la persona y se vuelve a preparar el
+ * encargo) se cambia, y el título sale de ella como al crear.
+ */
+export declare function conEncargo(tarea: Tarea, encargo: string, peticion?: string, 
+/** La pantalla de Stitch: una nueva la sustituye, `null` la QUITA, ausente no la toca. Ya comprobada por quien llama. */
+pantalla?: PantallaElegida | null): Tarea;
+/**
+ * La tarea con el veredicto del juez, si es que hay uno.
+ *
+ * `undefined` significa «no se le preguntó» y entonces no se toca el campo: se llega aquí
+ * también por los caminos que aparcan antes de llegar al juez —el proyecto que ya no está,
+ * el turno que revienta—, y escribir ahí una ausencia borraría el veredicto del intento
+ * anterior, que sigue siendo lo último que se supo del trabajo.
+ *
+ * Cuando SÍ hay veredicto, sustituye: ver `Tarea.veredicto`.
+ */
+export declare function conVeredicto(tarea: Tarea, veredicto: VeredictoDeTarea | undefined): Tarea;
+/**
+ * La tarea que una PERSONA da por buena, con la marca puesta.
+ *
+ * `conEstado` borra el `motivo` a propósito («el motivo vive SOLO en el estado que lo
+ * explica»), así que después de esto no queda ni una palabra que diga que aquí no hubo ni
+ * verificador ni juez: eso es lo que guarda `terminadaAMano`, y de ahí sale lo que la
+ * tarjeta pinta. El `veredicto` que hubiera **no se toca** — la persona lo pisa, no lo
+ * desmiente, y lo que el juez dijo sigue siendo lo que hay que poder leer al lado.
+ *
+ * La transición la decide `conEstado`, que LANZA si no vale: repetir esa regla aquí es como
+ * acaban divergiendo (el mismo argumento de `conFeedback`).
+ */
+export declare function darPorBuenaAMano(tarea: Tarea, ahora?: string): Tarea;
+/**
+ * Cuántas veces se reanuda SOLA una tarea cortada a mitad. Una: si vuelve a cortarse, puede ser ella la que tumba el
+ * proceso, y reanudarla siempre sería un bucle; entonces se aparca y espera a una persona.
+ */
+export declare const TOPE_DE_REANUDACIONES = 1;
+/**
+ * Lo que recibe el agente al reanudar, como un mensaje más en SU hilo. El trabajo de antes del corte está en el disco
+ * (las tareas escriben sin aprobación) y en su memoria hasta el último paso guardado, pero la llamada en curso se perdió:
+ * por eso manda MIRAR antes de rehacer.
+ */
+export declare const TEXTO_DE_REANUDACION: string;
+/**
+ * Una tarea que el proceso dejó «en proceso» al morir, REANUDADA: vuelve a la cola con `TEXTO_DE_REANUDACION` como
+ * feedback pendiente, que el corredor manda en su MISMO hilo (`peticionDeFeedback` con `reanudando`). Pasa por las
+ * transiciones de siempre —aparcada con su motivo y devuelta con un feedback—, así que no hay un atajo nuevo que vigilar.
+ *
+ * `undefined` = NO se reanuda y se aparca como hasta ahora: sin hilo que reabrir (empezar de cero sin decírselo a nadie
+ * podría rehacer o pisar lo escrito) o con el tope gastado.
+ */
+export declare function reanudadaTrasCorte(tarea: Tarea, motivo: string, ahora?: string): Tarea | undefined;
+/** El motivo de aparcar una cortada que YA se reanudó sola: lo de siempre, más por qué esta vez no sigue. */
+export declare const motivoTrasReanudar: (motivo: string) => string;
+/**
+ * «Continuar» en una tarea aparcada sin escribir nada: lo que entra en SU hilo como feedback. Sin esto, seguir sin
+ * añadir nada era «Reintentar», que vuelve a mandar el encargo entero.
+ */
+export declare const TEXTO_DE_CONTINUAR = "Contin\u00FAa donde lo dejaste.";
+/**
+ * ¿Se puede «Arrancar ahora»? Una tarea `nuevo` que no espera a ninguna anterior (`tras`): las encadenadas esperan a
+ * que la suya termine, y saltárselo sería arrancar sobre trabajo sin aceptar. La MISMA regla que `siguientesAEjecutar`.
+ */
+export declare function puedeArrancarYa(tarea: Pick<Tarea, "estado" | "tras">, lista: readonly Pick<Tarea, "id" | "estado">[]): boolean;