Agentes desatendidos en oMLX y gentle-shell

Introducción

Este artículo aborda una pregunta concreta: ¿es posible completar trabajo real de principio a fin con modelos locales, hardware de consumo y solamente tecnología open source?

Para investigarlo, desarrollamos un piloto de documentación: convertir manuales PDF y capturas antiguas en documentación en formato wiki, con imágenes de la nueva versión de ADempiere y un asistente que responde preguntas. La implementación combinó el servidor de inferencia oMLX, el harness de agentes Gentle Shell y modelos de pesos abiertos de la familia Qwen, ejecutados en una estación de trabajo personal.

Soy el mantenedor principal de ADempiere, un proyecto open source de ERP, CRM y SCM. Su repositorio oficial ofrece acceso público al código fuente y al historial de desarrollo, dando contexto al proyecto detrás de este piloto. También dirijo una empresa especializada en el desarrollo, soporte y mantenimiento profesional de soluciones basadas en esta tecnología. Esa experiencia nos ayudó a elegir una tarea concreta, útil y con resultados verificables.

El propósito no era comparar esta configuración con modelos de frontera ni con herramientas como Claude Code o Codex, sino establecer si podía completar el trabajo propuesto, identificar los obstáculos y documentar las condiciones necesarias para hacerlo posible.

A continuación comparto la experiencia, los problemas encontrados, las soluciones desarrolladas y los resultados obtenidos, junto con los límites de la evidencia.

Resumen ejecutivo

Probamos si modelos locales, hardware de consumo y herramientas open source podían realizar documentación sin intervención constante. El piloto utilizó modelos Qwen servidos por oMLX en un Apple M5 Max de 128 GB, con pi y gentle-shell coordinando agentes sobre una wiki de ADempiere.

• Para oMLX: las correcciones de decode TurboQuant por lotes y prefill con prefijos restaurados mejoraron el rendimiento medido. La propuesta de pausa y reanudación conservó solicitudes bajo presión forzada.
• Para gentle-shell: la reescritura del prompt de sistema por todo causaba pérdidas de caché. La corrección probada mueve las tareas a mensajes de conversación para mantener estable ese prompt.

Con las correcciones propuestas de oMLX y gentle-shell aplicadas durante el piloto, el proyecto alcanzó su objetivo: completar de principio a fin la documentación en formato wiki, con imágenes de la nueva versión de ADempiere y un asistente que responde preguntas, utilizando modelos locales, hardware de consumo y herramientas open source. Los benchmarks documentan mejoras de rendimiento, memoria y estabilidad; no auditan independientemente el contenido de la wiki. Los resultados históricos, las comparaciones recientes y la ejecución no pareada responden preguntas distintas.

Los resultados corresponden a una estación de trabajo de consumo de Apple preparada para IA local y una familia de modelos. Upstream integró PR2 como #4442 y la corrección de PR1 como #4453 el 2026-10-12; las demás correcciones son propuestas, no afirmaciones de integración en upstream, y ninguna es una garantía para equipos menores.

Resultados y límites de un vistazo

Cada resultado debe leerse junto con su línea base. Varias solicitudes dentro de una ejecución no son repeticiones independientes de un benchmark. Los enlaces de evidencia llevan a la configuración, los logs y los commits exactos.

De un vistazo

El caso de uso

La configuración es un Apple M5 Max (128 GB) que sirve un modelo local a varias sesiones del agente de programación pi. pi ejecuta encima el harness gentle-shell (paquete gentle-pi), que agrega el flujo de trabajo del agente: orquestación, una herramienta de tareas pendientes (todo), integración de revisión y delegación a subagentes. Los subagentes se ejecutan como procesos pi separados, cada uno con el mismo harness. Las sesiones leen archivos fuente completos y toman capturas de pantalla. Los prompts son grandes: en 1,260 solicitudes registradas la mediana fue de 107k tokens y el p90 de 168k. Cada turno reenvía la conversación creciente, por lo que la caché de prefijo decide si un turno cuesta 1 segundo o varios minutos.

El objetivo era simple de enunciar: dejar la máquina trabajando hasta que terminen todos los trabajos. Eso implica usar la memoria libre para concurrencia, no descartar nunca trabajo completado y pausar en lugar de abortar cuando la memoria escasea.

Ilustración de las grabaciones posteriores de fork.5, no un benchmark de la configuración original.

Qué fallaba en v0.7.0 estándar

• Varios prompts largos concurrentes alcanzaban el umbral duro (hard watermark) de la guardia de memoria (memory guard). Las solicitudes se abortaban a mitad del prefill, se perdía todo el progreso de prefill y el agente se detenía a esperar a una persona.
• Aumentar la concurrencia dejaba las cosas peor. En un benchmark mixto de 3 solicitudes, la ejecución concurrente terminó en 538 s frente a 246 s en serie, con 6 abortos.
• Cuando el decode por lotes sí se ejecutaba, las filas cortas de un lote TurboQuant con relleno a la izquierda producían salida degenerada.
• La reutilización de la caché de prefijo era alta en promedio, pero colapsaba en ráfagas: pérdidas de 70k–170k tokens en un solo turno.

Cómo se desarrolló

Premisas y resultados

Las revalidaciones más recientes aparecen más abajo. Las comparaciones originales se conservan como evidencia histórica; no son mediciones de la versión actual de upstream.

Revalidación sobre un upstream main más reciente

Ilustración de decode concurrente de las grabaciones de fork.5. Las mediciones pareadas B=3 de abajo son evidencia separada; este video B=5 no es una grabación de esas pruebas.

La evidencia anterior se midió sobre b7c7929e con el runtime de la app v0.7.0. Se volvió a comprobar sobre commits más recientes de upstream main en dos rondas: la premisa de PR1 sobre 25aebb3e (esta subsección) y luego el fork completo contra main c0b1056b (siguiente subsección). Cada rama propuesta para upstream está ahora rebasada sobre main 013bc3f3 (2026-10-10), con sus pruebas específicas y el comando de CI ejecutados de nuevo allí (Contribución propuesta). Los commits de upstream entre 25aebb3e y 013bc3f3 no tocan los archivos de TurboQuant que cambia PR1.

PR1 sobre 25aebb3e. PR1 estaba rebasado sobre 25aebb3e en ese momento, por lo que su premisa, P3, se volvió a ejecutar sobre ese árbol. main 25aebb3e y PR1 (61bd8a06, dos commits sobre 25aebb3e) se ejecutaron desde un mismo venv construido con las versiones fijadas de main: mlx 0.32.3, mlx-vlm 0.7.7, mlx-lm 94cdcae1, transformers 5.17.0. Entre ellos solo cambió el árbol de código fuente. Los prompts tienen unos 20k / 45k / 135k tokens, idénticos byte a byte a los de las ejecuciones anteriores, con 512 tokens nuevos y muestreo greedy. Tres filas B=3 se restauran desde la caché de prefijo, hacen decode juntas y se comparan con los mismos prompts restaurados con B=1. Una ejecución por build, un servidor a la vez, con la app en vivo cerrada.

• Rendimiento. Ninguno de los dos árboles aborta ni degenera. PR1 hace el decode por lotes 5.4× más rápido por fila con MTP activado y 12× más rápido con MTP desactivado, reduce la fase B=3 de 345 a 66 s y de 780 a 65 s, y baja el pico del proceso en 11–15 GB. Los 0.66 tok/s de main con MTP desactivado son lo que predice el microbenchmark: unos 86 ms por capa TurboQuant en la ruta con relleno, multiplicados por 15 capas. El decode con B=1 es de unos 40 / 29 / 17 tok/s con MTP activado, igual en ambos árboles, por lo que las filas por lotes siguen siendo más lentas que las filas individuales.
• Identidad frente a B=1, MTP desactivado. Aquí la referencia B=1 es determinista: una segunda ejecución B=1 es idéntica en ambos árboles. Las filas por lotes de main se apartan de ella alrededor del token 1–2 en las filas de 20k y 45k; las de PR1 alrededor del token 8–10, y alrededor del token 45 en la fila de 135k. Ninguna es idéntica token a token. Upstream no tiene volcado de logprobs, por lo que estas divergencias no se pueden clasificar como ruido de casi empates ni como un defecto. La separación más temprana en main es consistente con la atención de filas con relleno, pero no la demuestra.
• Identidad, MTP activado. Dos ejecuciones B=1 ya difieren entre sí, por lo que las divergencias de B=3 no dicen nada sobre el procesamiento por lotes.
• Qué cambió desde la evidencia anterior. Sobre b7c7929e con el runtime de la app v0.7.0 (mlx-vlm 0.7.1), main degeneró (4-gram de alrededor de 0.33 / 0.29 / 0.18 con 121 GB) en una ejecución y abortó (6 abortos por memoria con 120 GB) en otra. Ninguno de los dos casos se reproduce sobre 25aebb3e. Hay dos diferencias: los 52 commits de upstream intermedios (incluidos el rollback exacto de #3127 y cambios en la guardia de memoria y en la equidad del decode) y el runtime. Con una ejecución por build, no se sabe cuál de los dos lo eliminó.

El fork completo contra main c0b1056b

El fork se rebasó de nuevo, esta vez sobre upstream main c0b1056b (el commit etiquetado como v0.7.1.dev1). Ambos árboles se ejecutaron desde un mismo venv construido con las versiones fijadas de main (mlx 0.32.3, mlx-vlm 0.7.7), un servidor a la vez, con la app en vivo cerrada. El fork (6fbb3274) se ejecutó con la configuración de la app del fork; main se ejecutó con una configuración sin cambios. Los escenarios de presión forzada son los de C7 (más abajo): tres prompts greedy de unos 130k / 115k / 100k tokens iniciados con 0.5 s de diferencia, hard_threshold 0.8, el mismo techo personalizado para ambos árboles. La recuperación de buffers agrupados está ahora siempre activa, porque upstream eliminó la opción que la desactivaba. Una ejecución por escenario.

• Identidad tras una pausa, MTP desactivado. Cuatro pausas de decode forzadas por solicitud (12 en total, en los offsets de salida 100, 323, 1044 y 1706) dan una salida idéntica token a token en 3/3 solicitudes.
• Park durante un prefill empaquetado. El prefill empaquetado de upstream hace ahora el prefill de prompts concurrentes en un solo forward. Una fila estacionada mientras estaba empaquetada se reanudó, y las 3 solicitudes terminaron con 0 abortos. Las salidas difieren de las referencias en solitario solo en casi empates (un empate exacto y un margen de 0.125 nat), y un control con 56 GB sin ningún park diverge en los mismos tokens. La fila que nunca se estacionó es idéntica token a token con y sin el park de su compañera.
• Un defecto del fork encontrado y corregido durante esta ronda. Con 42 GB, la primera ejecución de decode con imágenes rechazó una solicitud solitaria que cabe por sí sola, basándose en una lectura de memoria que todavía incluía los buffers de una solicitud recién terminada. La corrección vuelve a medir antes de decidir y renueva el presupuesto de desalojo de la solicitud cuando salen las filas que esperaba (TDD estricto); la nueva ejecución pasó con 42 y 44 GB.

Premisas, fork contra main c0b1056b, mismo venv:

La primera medición de P6 (3 ejecuciones, 256 tokens de decode cada una, sin intercalar) mostró el decode del fork un 7.1% más lento, lo mismo con todas las opciones del fork desactivadas. No se reprodujo. Una nueva medición con 1,024 tokens de decode y tres sesiones intercaladas por árbol, MTP activado, da las medianas de la tabla, y un costo por ciclo de verificación de +0.9% (error estándar 1.4%) con 110k tras controlar por los tokens propuestos por el borrador. Con MTP desactivado, ambos árboles hacen decode a 16.8–17.0 tok/s con 110k y a 24.9–25.4 con 20k. La primera diferencia se debió a la aceptación de MTP en una muestra corta (1.90 frente a 2.01 tokens por ciclo) más la deriva entre ejecuciones no intercaladas, por lo que se cerró como ruido sin hacer bisect.

Revalidación con la corrección de prefill: fork 4aa66150 contra main 013bc3f3

Las ejecuciones anteriores son previas a la corrección del prefill tras un prefijo restaurado, que cambia cómo continúa un park reanudado o una solicitud reenviada sobre bloques TurboQuant restaurados. Por eso, los escenarios de presión forzada y P1/P2 se ejecutaron de nuevo en el fork con la corrección (4aa66150), contra main en 013bc3f3, con el mismo venv, techos, prompts y configuración. En cada reanudación se verificó en el log la línea dequantized … restored TurboQuant layers de la corrección, o su alternativa Kept … quantized, y la reserva que le sigue. Una ejecución por escenario.

• El prefill con imágenes es donde se nota la corrección. Cada prompt con imagen restaura un bloque de 2,048 tokens desde la caché paginada. Antes de la corrección, ese pequeño prefijo cuantizado mantenía todo el prefill de 100k–130k en la ruta cuantizada: TTFT de 1,797 / 1,267 / 2,130 s con dos parks. Con la corrección: 249 / 460 / 637 s. Las capas densas forman parte ahora de la reserva de prefill, por lo que la admisión ejecuta los prompts uno tras otro. Con 42 GB, un prompt admitido junto a otro, ambos densos, se estacionó bajo presión dura 4.6 s después, se reanudó solo, se descuantizó de nuevo y se completó, con un pico de 37 GB. Eso es un park y una reanudación a través del paso denso en hardware real, sin abortos.
• Reenvío tras una cancelación (P1, 2 ejecuciones por árbol). El fork conserva 73,728 tokens y hace el reenvío en 80.0 y 82.0 s. main no conserva nada y hace el reenvío en 192.0 y 193.0 s, lo mismo que su prefill en frío. Antes de la corrección, el mismo código del fork tardaba 198.9 s. El log muestra dequantized 15 restored TurboQuant layers (73728 tokens) for a 36302-token suffix prefill in 0.42s y luego una reserva sobre 16 cachés (+2.22 GB).
• Dos prompts concurrentes de 130k (P2). 2/2, 0 abortos, pico de 53 GB, tiempo total de 574 s, frente a 51 GB y 564 s antes de la corrección. Sin regresión; no interviene ninguna restauración.
• Identidad tras una pausa, MTP desactivado. 12 pausas forzadas por ejecución, todas reanudadas de forma exacta. Dos solicitudes son idénticas token a token; la tercera se aparta en un casi empate de 0.125 nat. Su deriva empieza en el token 4, antes de su primera pausa, tras un throttle de prefill puntual. El commit anterior a la corrección da los mismos tokens en la misma sesión (idénticos en logprobs, 2,000/2,000), por lo que ni la corrección ni la ruta de pausa lo causan.
• Prefill empaquetado. La salida con presión es igual al control sin presión (la ejecución con 42 GB difiere de él en un empate exacto), y ambas se apartan de las referencias en solitario en los mismos tokens, como antes. En esta sesión nunca se estacionó una fila empaquetada, por lo que esa ruta no se volvió a ejercitar.

Defecto de upstream: prefill de sufijo lento tras un prefijo TurboQuant restaurado

Ilustración de prefill concurrente de las grabaciones anteriores de fork.5, no una grabación de la corrección de prefijo restaurado ni de su benchmark pareado de abajo.

Rastrear la falta de ganancia de TTFT de P1 sobre c0b1056b llevó a un segundo defecto de TurboQuant en upstream. Tras un hit de prefijo en la caché SSD paginada, el sufijo no cacheado de un prompt hacía prefill unas 2.4× más lento por token que un prefill en frío de las mismas posiciones. Se reproduce sobre main, por lo que no es un bug del fork, y con TurboQuant desactivado ambos tardan lo mismo.

Mecanismo

• Un hit en la caché SSD paginada restaura las capas TurboQuant como objetos TurboQuantKVCache cuantizados (#1842), y el scheduler las mantiene cuantizadas mientras hace el prefill del sufijo.
• Cada chunk de cada capa TurboQuant atiende entonces a todo el prefijo cuantizado a través de la ruta de atención cuantizada por mosaicos, nunca SDPA denso, por lo que el costo crece con la longitud del prefijo.
• La reserva de capacidad de prefill informa across 1 caches tras una restauración de ese tipo en lugar de 16, porque solo la última capa, no cuantizada, es un KVCache simple que puede planificar. Esa línea es un síntoma, no la causa.

Corrección

Antes de un sufijo que necesita más de un chunk de prefill, el scheduler copia una sola vez las capas TurboQuant restauradas en capas KVCache densas, de modo que los chunks del sufijo siguen la misma ruta densa que un prefill en frío. Al final del prefill solo se cuantiza el sufijo y se agrega a la caché TurboQuant original, por lo que los códigos del prefijo restaurado se reutilizan bit a bit en lugar de cuantizarse de nuevo. El paso se ejecuta solo cuando las capas densas, dimensionadas para todo el prompt, caben bajo el objetivo de pico de prefill, la misma condición que la reserva de prefill; de lo contrario, registra en el log que conservó el prefijo cuantizado. Un sufijo de un solo chunk, como un turno de chat, mantiene la ruta actual. Dos commits con 16 pruebas, sobre main 013bc3f3.

Resultados

Qwen3.8-27B, KV TurboQuant de 4 bits en 15 de 16 capas KV, un servidor a la vez desde el venv con versiones fijadas. A = 73,787 tokens, almacenado; B = A + 36,358 tokens con un hit de prefijo de 73,728 tokens; las posiciones [73,728, 110,086) de B se comparan con un prompt en frío de la misma sesión. Una ejecución por configuración.

• TTFT de B: 198.8 s en main, 87.9 s con la corrección. La copia densa puntual de 15 capas × 73,728 tokens tarda 0.43 s.
• Calidad (MTP desactivado, greedy, 512 tokens, logprobs por token desde un hook de depuración local): en frío frente a en frío es idéntico. La salida restaurada, con o sin la corrección, se aparta de la de en frío solo en casi empates (un margen de 0.125 nat, un paso de logprob de bf16), en los mismos tokens, porque el propio prefijo cuantizado desplaza la distribución. Con y sin la corrección, las salidas restauradas coinciden durante los primeros 239 y 97 tokens, y luego se separan en empates exactos.
• Memoria: la reserva tras una restauración planifica ahora las capas densas (16 cachés, +2.23 GB en lugar de 1 caché, +0.14 GB), y las guardias de memoria las ven como uso actual. El pico de prefill es de 26.29 GB frente a 25.22 GB para un prompt en frío de la misma longitud; la diferencia es el prefijo cuantizado, de alrededor de 1 GB, que se conserva hasta el final del prefill.
• Prueba rápida en vivo con fork.7 (kernels compilados): un prompt de 41,323 tokens con 24,576 tokens restaurados registró dequantized 15 restored TurboQuant layers (24576 tokens) for a 16746-token suffix prefill in 0.16s y una reserva sobre 16 cachés. El TTFT fue de 20.6 s, frente a 53.9 s para el mismo prompt en frío.

La estrategia: pausar, no abortar

La idea más valiosa del proyecto fue cambiar la pregunta. Cuando la memoria alcanza el límite duro, el servidor estándar aborta las solicitudes en curso, lo que descarta todos los tokens a los que ya se les hizo prefill y todos los generados. Nos preguntamos si el servidor podía pausar una solicitud en su lugar. La caché SSD paginada ya existía y hace que una pausa sea barata.

La primera versión, el park, cubría solo el prefill por chunks. Un benchmark de forzado (P7) mostró que funciona, y también dónde se detiene. El siguiente pico afectó a una solicitud en decode, que no se podía pausar, y las tres solicitudes se abortaron. Eso llevó al ciclo completo. Pausa y reanuda solicitudes en prefill y en decode, incluidos los prompts con imágenes, y rechaza con un error estructurado una solicitud que nunca podrá caber. A continuación se describe qué hace el código, verificado contra la implementación (omlx/scheduler.py, omlx/process_memory_enforcer.py, omlx/settings.py).

La primera versión: estacionar un prefill

1. Guardar el progreso durante el prefill (D1, prefill_progress_commit_blocks). Cada N bloques completados (4 bloques de 2048 tokens en la app del fork), los bloques con prefill se almacenan en la caché SSD paginada bajo la tabla de bloques propia de la solicitud. Esto requiere la caché SSD. Sin ella se omite el commit y un park se reanuda en frío.
2. Estacionar en lugar de abortar (T7, memory_pressure_park). Con presión dura (no de emergencia, y dentro de un presupuesto de 30 sondeos de aplazamiento), el enforcer de memoria pide al scheduler que estacione a una víctima antes de considerar un aborto. El scheduler descarta la caché KV en vivo de la víctima, lo que libera la memoria. Conserva el stream del cliente, el prompt, los parámetros de muestreo y la hora de llegada. Fija los bloques confirmados contra el desalojo, tanto en el pool de bloques en memoria como en el índice del SSD. La solicitud sigue registrada y en espera, y el cliente no recibe ningún error.
3. Reanudar desde la caché fría. En la primera versión, una solicitud estacionada se readmitía tras park_resume_ok_polls (3 por defecto) sondeos ok consecutivos, cuando el monitor quedaba en silencio, o cuando no se podía admitir nada más. La readmisión hace una búsqueda de prefijo normal, que restaura los bloques confirmados, y el prefill continúa desde el último límite confirmado. El ciclo completo reemplazó esta regla de reanudación por una consciente de la memoria (más abajo).

Forzarlo: el benchmark de park P7

La configuración consistía en tres prompts largos concurrentes de unos 130k, 115k y 100k tokens, iniciados con 0.5 s de diferencia, en un servidor aislado. Usaba un techo de memoria personalizado bajo (42 GB, umbral duro al 80%), y la recuperación de buffers agrupados estaba desactivada para que la presión llegara a la decisión de park. Lo ejecutamos una vez con prompts solo de texto y otra con una imagen al principio de cada prompt, en el fork completo y en upstream main, un servidor a la vez.

07:04:13  Hard memory pressure: parking a prefill victim on 1 scheduler(s) instead of aborting (poll 1/30)
07:04:13  Parked request e2f2… at 129024 tokens committed (park 1/3), reason: hard memory pressure
07:04:14  Resumed parked request e2f2…: cached=129024
07:04:23  Park skipped for e2f2…: decoding, not in chunked prefill (memory pressure falls back to abort)

P7 demostró que la ruta funciona: una solicitud en prefill se pausó, se liberó su memoria y se reanudó desde la caché SSD en alrededor de medio segundo con todos los tokens confirmados restaurados. No salvó un lote, porque las filas en decode y los prompts con imágenes seguían recurriendo al aborto.

El ciclo completo

1. Víctima única (C1). Cuando no hay nada que se pueda pausar, abortar una sola víctima (la de mayor KV en vivo, la más reciente en caso de empate) en lugar de todas. El enforcer espera a que esa memoria se libere antes de elegir otra. La emergencia y la descarga del modelo mantienen el abort-all. Opcional (opt-in): OMLX_MEMORY_ABORT_SINGLE_VICTIM.
2. Pausa y reanudación del decode (C2). Primero se emite el token muestreado pendiente. Se extrae la KV de la fila y se almacena como una cadena SSD exacta, asociada a la solicitud y fijada, y la fila sale del lote mientras su stream sigue abierto. Se guardan el sampler, los procesadores de logits, la posición de la secuencia de parada, el estado del parser y el max_tokens restante. La reanudación restaura la cadena y vuelve a insertar la fila sin prefill, y el RNG no se vuelve a sembrar. Una fila singleton de Lightning MTP se transfiere primero al decode estándar. Se excluyen las filas de MTP por lotes, DFlash, VLM-MTP y SpecPrefill.
3. Reanudación consciente de la memoria (C3). Una solicitud pausada se reanuda cuando la memoria libre estimada cubre su necesidad: la KV de su longitud final más un margen transitorio. Nunca se reanuda bajo presión dura. FIFO entre las solicitudes pausadas, y la retención de cabeza de línea reserva el espacio.
4. Nunca cabe frente a cabe más tarde (C4). Si pesos + KV(prompt + max_tokens) + transitorio superan la capacidad, la solicitud recibe HTTP 400 context_exceeds_capacity con siete campos numéricos y retryable: false. Una solicitud que cabe por sí sola espera en su lugar. GET /v1/omlx/capacity y el encabezado X-oMLX-Max-Context-Tokens exponen las cifras.
5. Compactación en el harness (C5, lado del cliente). La extensión de pi compacta y reintenta ante context_exceeds_capacity, y fija su umbral de compactación a partir del endpoint de capacidad. Tiene pruebas unitarias, pero todavía no tiene validación en vivo.
6. Prompts con imágenes (C6). Un sufijo solo de texto tras una última imagen en caché pasa por el prefill en la ruta por chunks, de modo que se puede pausar. Esta ruta se toma solo tras comprobar que las posiciones mRoPE del sufijo son arange + delta en cada plano. Opcional (opt-in): OMLX_MEDIA_TEXT_SUFFIX_CHUNKED.

La pausa y reanudación están detrás de memory_pressure_park (desactivado por defecto). La condición de nunca cabe, la espera de cabe más tarde y un reloj de bloqueo de admisión basado en el progreso están detrás de memory_scheduling (auto | on | off, auto por defecto). auto los activa solo cuando la guardia de memoria tiene un techo explícito (el nivel custom); de lo contrario, la admisión se mantiene como en main. Todas las ejecuciones C7 fijaron un techo personalizado, por lo que su evidencia es válida con el valor por defecto.

C7: el benchmark extendido, y qué falló primero

C7 extiende P7 a la presión durante la fase de decode, a los prompts con imágenes, a una solicitud que nunca cabe y a la identidad greedy tras una pausa. El objetivo es 0 abortos, con un servidor a la vez y la app en vivo cerrada. La primera ejecución (rama e80eb1f7, techo de 42 GB, hard 0.8, una ejecución por par) no lo cumplió:

Cada pausa registró restored N tokens exactly (bloqueo de 1.6–3.5 s), por lo que la mecánica funcionaba. Las brechas estaban en la política y en el cableado. Cada una se rastreó hasta una causa raíz en los logs del servidor y se corrigió con pruebas primero, un commit por cada una:

Dos ejecuciones intermedias muestran la progresión:

• Tras D1–D3 (31cab33d, 48 GB): nunca cabe pasó, el decode con imágenes terminó 3/3 con 0 abortos y no se activó ningún abort-all. Pero el decode de texto (dos veces) y el prefill con imágenes terminaron 2/3: la tercera solicitud falló por el timeout de bloqueo de admisión, lo que llevó a D5.
• Tras D5–D6 (f3c11356): el decode de texto y el de imágenes terminaron 3/3. El prefill con imágenes con 46 GB todavía terminó 2/3, lo que llevó a D7.

Resultados finales

Mismo modelo, máquina y escenarios, una ejecución por par. main (b7c7929e) ejecutó los mismos escenarios con 48 GB. La ejecución de prefill con imágenes de la rama usó 46 GB, lo que es más duro para la rama.

Nunca cabe (42 GB, 31cab33d), un prompt de 60k tokens con max_tokens 2,000,000:

Identidad greedy tras una pausa. B=1 con 56 GB, de modo que no hay pausa por memoria, y pausas de decode forzadas en los offsets de salida 100, 323, 1044 y 1706. Cada ejecución de prueba se compara con una ejecución sin pausas.

Premisas frente a main, medidas en e80eb1f7, antes de D1–D8:

Comandos de reproducción

El harness es benchmarks/unattended/bench_premises.py en la rama del fork bench/p7-park (95dd47e8). Superpone el omlx/ de un checkout sobre el runtime de la app. Ejecute un solo servidor oMLX a la vez, con todas las demás instancias cerradas. La variante fork fija OMLX_MEMORY_PRESSURE_PARK=true y OMLX_PREFILL_PROGRESS_COMMIT_BLOCKS=4.

# branch build: export once, so every command below gets the same env
export OMLX_BENCH_FORK_REPO=<pause-resume checkout>
export OMLX_BENCH_EXTRA_ENV=OMLX_DISABLE_PRESSURE_RECLAIM=1,OMLX_MEMORY_ABORT_SINGLE_VICTIM=true,OMLX_MEDIA_TEXT_SUFFIX_CHUNKED=true

# references for one scenario: alone, 56 GB
python benchmarks/unattended/bench_premises.py --variant fork --premise C7 \
  --c7-scenario decode --runs 1 --p7-ceiling-gb 56 --c7-refs-only --out refs/ref-decode

# pressure run: decode | image-decode at 48 GB, image-prefill at 46 GB
python benchmarks/unattended/bench_premises.py --variant fork --premise C7 \
  --c7-scenario decode --runs 1 --p7-ceiling-gb 48 --c7-refs-from refs/ref-decode --out out/branch-decode

# never fits
python benchmarks/unattended/bench_premises.py --variant fork --premise C7 \
  --c7-scenario never-fits --runs 1 --p7-ceiling-gb 42 --out out/branch-never-fits

# identity with MTP off: references, then forced pauses
python benchmarks/unattended/bench_premises.py --variant fork-nomtp --premise C7 \
  --c7-scenario identity --runs 1 --p7-ceiling-gb 56 --c7-refs-only --out out/idrefnm
python benchmarks/unattended/bench_premises.py --variant fork-nomtp --premise C7 \
  --c7-scenario identity --runs 1 --p7-ceiling-gb 56 --c7-refs-from out/idrefnm \
  --c7-force-pause-at auto --out out/idforcenm

# main build: re-export, then run the same scenario commands (with main's own --out paths)
export OMLX_BENCH_FORK_REPO=<main checkout>
export OMLX_BENCH_EXTRA_ENV=OMLX_DISABLE_PRESSURE_RECLAIM=1

# unit and rig tests, then upstream's CI selection (needs pytest-xdist, as CI installs it)
pytest tests/test_scheduler_decode_pause.py tests/test_memory_resume_thrash.py \
  tests/test_memory_external_prefill.py tests/test_scheduler_capacity_vlm.py \
  tests/test_scheduler_forced_decode_pause.py tests/test_scheduler_solo_admission.py
pytest tests/ -m "not slow and not integration" -n 3 --dist loadgroup

Nuestras ejecuciones también pasaron OMLX_BATCHED_DECODE_HOLD_MAX_S=120, OMLX_MID_SYSTEM_POLICY=inline_note y OMLX_THINKING_RETENTION_GUARD_TOKENS=20000 a ambas builds. Pertenecen a otras funcionalidades del fork, y main las ignora. Prompts de los escenarios: unos 130k, 115k y 100k tokens, iniciados con 0.5 s de diferencia, greedy, max_tokens 2000 (32 para el prefill con imágenes).

Ejecución en producción real (fork.5)

Los resultados de C7 provienen de presión forzada en un servidor aislado. Después ejecutamos el fork empaquetado como servidor diario para trabajo real de agentes de programación desatendidos: pi con el harness gentle-shell, una sesión orquestadora y cuatro subagentes de gentle-shell haciendo captura de documentación guiada por navegador para un proyecto de documentación, más una segunda sesión de agente no relacionada. Cada solicitud fue al modelo local a través de la fijación del perfil.

Las solicitudes abiertas son las que tienen un stream abierto, en ejecución o en cola, y las que están en espera son las encoladas (ambas desde /api/status). La memoria libre del sistema proviene de memory_pressure de macOS e incluye los navegadores de los agentes y otras apps. La eficiencia de caché es la cifra acumulada del panel al final de cada nivel.

• Concurrencia elevada en vivo. Con un límite de 5 la cola casi se vació (promedio en espera 2.2 → 0.1), mientras que la eficiencia de caché se mantuvo en 94.5–95.4%.
• Decode por lotes con B=4 y B=5. Sobre upstream main b7c7929e con el mismo runtime de la app v0.7.0, P3 con B=3 degeneró o abortó. Sobre un main más reciente 25aebb3e se completa, pero el decode por lotes con relleno se ejecuta a alrededor de 1.5 tok/s por fila (revalidación de P3).
• Arranques en frío cuando una oleada llega de golpe. Las primeras solicitudes de cada oleada (unos 18k tokens, en su mayoría el prompt de sistema compartido) llegaron juntas. De 8, 5 hicieron prefill en frío en paralelo (58–129 s) y 3 reutilizaron 16,384 tokens compartidos (87–91%). Después de eso, cada turno de subagente fue de solo agregado.
• Throttle de prefill de upstream. El throttle adaptativo de prefill de upstream pausó prefills por chunks 21 veces en 14 solicitudes para redimensionar los chunks. La memoria de proceso más alta que registró fue de 46.6 GB. No se trata de la pausa y reanudación del fork.
• La planificación de memoria se mantuvo activada todo el tiempo. El log muestra líneas "Memory scheduling: off" en grupos de cuatro u ocho (00:27, 03:02, 03:08, 04:19, incluidos momentos sin cambios de configuración). Provienen de la página de configuración de administración, que construye cuatro enforcers desechables (uno por nivel de memoria, modo por defecto auto) para previsualizar los techos de cada nivel; el enforcer en vivo se mantuvo activado, como confirman el endpoint de capacidad y el encabezado de contexto. Las líneas engañosas están corregidas en el fork (04bb7899, propuesto a upstream con el slice G): solo el enforcer en vivo registra su estado, y la API de configuración de administración informa el estado efectivo como memory_scheduling_effective. Por lo tanto, los conteos en cero de admisiones en solitario, esperas de admisión y nunca cabe reflejan una carga de trabajo que nunca se acercó a los límites de memoria, no funcionalidades desactivadas.

Hallazgos del harness en las mismas sesiones

Las mismas sesiones también sacaron a la luz cambios de prompt del lado del harness. Se enumeran en la sección de gentle-shell.

Material grabado en campo: carga sostenida

Grabaciones de pantalla de la misma noche (alrededor de las 04:28–04:43, poco después de la ventana medida), aceleradas. El panel de oMLX se muestra en su configuración regional en español. El contenido de la terminal y del IDE está pixelado por privacidad; las cifras del panel son las grabadas. Era una carga normal, por lo que no aparece ninguna pausa ni reanudación en pantalla; la evidencia de pausa y reanudación son las ejecuciones de presión forzada de C7 de más arriba. Los controles permiten pausar, volver a reproducir e inspeccionar las grabaciones. Los otros videos acompañan las secciones del caso de uso, decode por lotes y prefill.

Qué se construyó

La investigación de la reutilización de caché

Sin abortos, el costo pasó al re-prefill. Atribuimos a una causa cada ruptura grande de caché en el tráfico registrado. Las rupturas provenían de cambios del prompt en el medio, lo que invalida todo lo que viene después.

La causa más grande estaba en el harness. Cómo se encontró, qué costó, la corrección y su validación están en la sección de gentle-shell.

El cambio A1 del lado del servidor es complementario. pi también envía los cambios del prompt de sistema como mensajes de sistema a mitad de la conversación, y la alternativa strict de oMLX los volvía a fusionar en la cabeza. Cualquier cliente que haga lo mismo se beneficia de A1.

preserve_thinking: true, medido de nuevo

El resultado anterior. En el modelo de 8 bits con decodificación especulativa DFlash, conservar todo el razonamiento anterior daba una reutilización casi perfecta, pero alrededor de los 53k tokens de contexto el modelo empezaba a emitir </think> literales y XML de llamadas a herramientas sin procesar como texto, su aceptación del borrador caía del 65% al 54% y la sesión no se recuperaba. A2 se diseñó en torno a ese resultado. Conserva el razonamiento solo dentro del bucle de agente actual y lo elimina en los mensajes reales del usuario, exactamente como hace la plantilla con preserve_thinking: false. Una guardia determinista lo elimina una vez cuando el razonamiento retenido del bucle supera N tokens, y luego se mantiene de solo agregado. La guardia está fijada en 30k.

La pregunta. Con false, cada mensaje con rol de usuario elimina el razonamiento del segmento anterior, por lo que el prompt se reduce y el prefill se reinicia en el primer mensaje del asistente de ese segmento. pi envía los avisos del harness (actualizaciones de todo, resultados y despertares de subagentes, avisos de trabajos en segundo plano) como mensajes con rol de usuario, por lo que provocan la misma eliminación. Esa era la última pérdida de caché que quedaba en la sesión principal tras la corrección de gentle-shell. true nunca se había probado durante mucho tiempo en el modelo actual (oQ4e de 4 bits con Lightning MTP), así que lo medimos el 2026-10-11.

Método. La app instalada fork.7 era el único servidor en ejecución. La configuración se cambió en tiempo de ejecución a través de la API de administración (PUT /admin/api/models/<id>/settings, que se aplica sin recargar y persiste), tras un respaldo de la configuración del modelo. El cliente fue el gentle-shell instalado en modo RPC de pi. Cada solicitud de pi se asoció a su línea en el log del servidor mediante sus conteos de tokens de prompt y en caché.

• P1, escenario del harness. Una sesión principal con una lista de tareas pendientes, un subagente en primer plano, un subagente en segundo plano y su despertar, un trabajo en segundo plano y su aviso, y dos prompts de seguimiento. true se comparó con una ejecución false del mismo driver en el mismo servidor.
• P2, sesión larga y realista. Un guion fijo de 27 prompts de programación reales sobre un clon temporal del fork de oMLX: leer y explicar código, encontrar puntos de llamada, escribir y ejecutar pruebas unitarias, corregirlas, escribir un parser de logs con pruebas, usar git. Hizo 99 llamadas a herramientas en cada ejecución. La ejecución true agotó su presupuesto de 110 minutos tras 27 prompts. El control false ejecutó después los mismos 27 prompts. Contamos marcadores de degeneración en el texto del asistente, en los argumentos de las herramientas y en el razonamiento: <think>/</think> literales, <function=, <parameter=, <tool_call>, bucles de repetición en el texto visible, paradas por longitud y errores de parseo de llamadas a herramientas. Las señales del detector de repetición en el razonamiento se presentan por separado a continuación.

Configuración fija en todas las ejecuciones: razonamiento forzado activado (presupuesto de 3,000 tokens), la guardia de retención de 30k activada, MTP activado, KV TurboQuant de 4 bits, temperatura 1.0.

Auditoría de los registros primarios. El recuento de tool_errors en preserve-thinking/p2-false-turns.jsonl da 7 y corrige los 9 reportados antes. El archivo correspondiente p2-true-turns.jsonl contiene 3 señales del detector thinking_loops; el resumen original solo contaba loops en texto visible. El detector señala líneas de al menos 30 caracteres repetidas al menos cuatro veces dentro de un mensaje. Estas señales siguen sin clasificar y pueden incluir falsos positivos; no son degeneración confirmada. Los registros locales se auditaron sin volver a ejecutar el experimento y actualmente no se enlazan como un archivo público.

En P1, true hizo que las 11 solicitudes de la sesión principal fueran hits de prefijo completo, frente a 4 divergencias alineadas a bloques en 13 con false. Los tokens no cacheados bajaron de 6,208 a 1,803 y el prefill sumado de 17.2 a 8.1 s. Las sesiones de subagentes y de trabajos se comportaron igual con ambas configuraciones.

Hallazgos.

• Sin degeneración visible confirmada con true en este modelo hasta 200k de contexto; las señales de repetición en razonamiento siguen sin clasificar, alrededor de 4× el punto en que falló la configuración de 8 bits con DFlash. La aceptación de MTP se mantuvo estable, y las comprobaciones puntuales a 90k, 115k, 121k y 196k citaron correctamente código y referencias archivo:línea del contexto. El único desliz fue a 125k: el modelo ejecutó un comando en una ruta de documentación citada en el prompt de sistema del harness y se corrigió en la llamada siguiente. Se trata de una ejecución por configuración con temperatura 1.0, por lo que es evidencia, no prueba.
• La ganancia de caché es real, pero pequeña con estos tamaños de segmento. true eliminó todas las divergencias en los límites, pero aquí cada turno agregaba solo 1–15k tokens, por lo que una divergencia costaba unos pocos segundos. El re-prefill de varios minutos observado con false en el uso diario (unos 560 s con 135k) requiere un turno que lea decenas de miles de tokens de archivos antes del siguiente mensaje del usuario. Este guion no produjo ninguno.
• true tiene un costo: el contexto se llena alrededor de 1.5× más rápido, porque todo el razonamiento permanece en él. El modelo además razonó alrededor de 2.4× más en esa ejecución, y el decode se ralentiza a medida que crece el contexto. Los mismos 27 prompts tardaron 1.8× más, y el prefill sumado fue aproximadamente igual, porque true hizo prefill de un contexto mucho más largo. Parte del razonamiento adicional puede deberse a la varianza del muestreo.
• Factor de confusión: la guardia de retención de 30k se mantuvo activada en ambas ejecuciones. Con true nunca se activó; el prompt nunca se redujo.

Decisión. No se observaron marcadores literales de degeneración con true en esta única ejecución sobre este modelo; las señales del detector de repetición en razonamiento siguen sin clasificar y estas observaciones no demuestran la ausencia de riesgo de calidad. El 2026-10-11 se activó en el uso diario para seguir observándolo en cargas de trabajo donde algunos turnos leen archivos grandes, aceptando los costos medidos en crecimiento del contexto y tiempo total. Lo que hay que vigilar son los marcadores de degeneración, el TTFT en los límites, la frecuencia con que las sesiones llegan a la compactación y el tiempo total por tarea. La guardia de A2 se mantiene en 30k como respaldo.

Resultado en vivo

• Turnos que agregan una imagen nueva: 10 de 10 tuvieron un hit de 97.4–99.7%, por lo que solo se hizo prefill del nuevo resultado de herramienta y de la imagen.
• Turnos consecutivos tras la corrección del cliente: 31 de 31 estrictamente de solo agregado.
• Eficiencia de caché a nivel de sesión en el panel: 95.2–95.3%.

gentle-shell: hacer el harness compatible con la caché

Esta sección está dirigida a los mantenedores de gentle-shell. La mayor pérdida individual de caché de este informe estaba en el harness, no en oMLX. Mientras había tareas pendientes abiertas, la extensión de todo de gentle-shell reescribía el prompt de sistema en cada prompt del usuario. En alrededor de 1.5 días de uso real causó unos 1.05M tokens con re-prefill, aproximadamente 80–85 minutos de tiempo de GPU, y turnos que tardaban 2–6 minutos en lugar de segundos. Mejoramos el harness con el mismo método que el servidor, y la corrección está lista en fix/todo-prompt-cache-1367, registrada en #1367.

Las pruebas existentes del harness no expusieron el costo de caché: la herramienta de todo se comportaba correctamente y ninguna solicitud fallaba, pero algunos turnos del agente tardaban minutos en lugar de segundos. Identificamos la causa al ejercitar el harness contra un servidor de inferencia local cuyo comportamiento de caché podíamos observar. Las pruebas de estabilidad del prompt pueden detectar la reescritura en sí; las mediciones del servidor establecen su costo operativo.

El proceso

Lo que costó en el servidor

Esto corresponde a alrededor de 1.5 días de uso real, todo en una sola máquina. Las cifras marcadas con ≈ se derivan de tasas medidas.

En una API alojada, un prefijo modificado puede reducir la entrada cacheada y aumentar la latencia o el costo, según las reglas de caché y los precios del proveedor. Aquí no se hizo ningún experimento de caché o facturación con proveedores alojados; los efectos medidos corresponden a la configuración local probada.

Cómo se identificó la invalidación

1. El síntoma en el panel. Durante el uso normal, el panel de oMLX mostraba una y otra vez prefills largos (la barra de progreso azul) en turnos que deberían haber sido casi gratuitos. Un ejemplo: 43.2k tokens a unos 300 tok/s en un prompt de 80k. El decode de una solicitud concurrente quedaba congelado detrás ("last token 46 s ago").
2. El diagnóstico del propio servidor. El log de la caché de prefijo para esa solicitud dice:

   prefix cache restore: cached=36864 suffix=43171
   re-prefills 43171 of 80035 tokens; closest stored sequence shares the first 37735

   La misma sesión volvió a divergir más tarde en 37,739 tokens. Una divergencia en el mismo lugar cada pocos turnos apunta a algo que reescribe el prompt en una posición fija, no a un desalojo.
3. Descartar la caché del servidor. Se contrastó el desalojo del SSD con las pérdidas: la caché guarda unas 8 horas de historial, y ninguna de las pérdidas grandes coincidía con desalojos. Las recargas del modelo ocurrieron con horas de diferencia. La cuadrícula de bloques explica como máximo 2,047 tokens por evento.
4. La diferencia del lado del cliente. Comparar los payloads registrados de dos solicitudes consecutivas de esa sesión mostró la primera diferencia dentro del mensaje de sistema, en el carácter 70,384 de unos 104,700. Eso equivale aproximadamente al token 37.7k, lo que coincide con el punto de divergencia del servidor:

     …pending: install dependencies and verify loading.
   + (stale: 2 turns without an update — bring the list up to date now)
     </addendum>

5. Atribución entre sesiones. Hacer lo mismo en todas las sesiones registradas atribuyó unos 945k tokens con re-prefill en las sesiones principales y unos 107k en los subagentes a cambios en el prompt de sistema o en la sección de herramientas. El apéndice de todo fue el factor principal.
6. Confirmación. Tras la corrección, el prompt de sistema de la misma sesión dejó de llevar el estado de todo a las 00:26:37. Cada turno posterior fue de solo agregado, salvo una ruptura de caché esperada en el cambio.

La corrección: mantener estable el prompt de sistema

El harness gentle-shell agregaba un bloque de todo al prompt de sistema en cada prompt del usuario. Cuando la lista quedaba desactualizada, agregaba un contador, (stale: N turns without an update …), que cambiaba en cada prompt. El bloque estaba alrededor del token 30–35k de un prompt de sistema de ~41k, seguido de otras secciones. En las sesiones padre afectadas, cada incremento o edición de todo rompía la reutilización del resto del prompt de sistema y de la conversación posterior. Esto no se aplica a todos los subagentes: en las versiones de upstream examinadas en las nuevas pruebas, los hijos y trabajos en segundo plano con GENTLE_PI_AGENTS_CHILD=1 no cargan el hook de todo. Por lo tanto, no todos los cambios del prompt de sistema o de la sección de herramientas registrados en tráfico de hijos deben atribuirse a este hook. Algunos turnos individuales perdieron así 70k–110k tokens de caché.

Lo corregimos en el harness. El prompt de sistema es ahora estable byte a byte dentro de una sesión. El estado de todo viaja como un mensaje de conversación persistido, enviado solo cuando la lista cambia realmente. El recordatorio de obsolescencia se activa una sola vez, sin contador. Tras una compactación, el estado se vuelve a inyectar una vez. La corrección está probada (45/45 pruebas de todo, con las fallas no relacionadas reproduciéndose sobre una base limpia), se usó a diario y está propuesta a upstream en gentle-shell #1367. La validación siguiente se ejecutó sobre la rama de la corrección fix/todo-prompt-cache-1367 en 955523df (2026-10-05, gentle-shell 4.0.0), no sobre upstream main.

• Solicitudes registradas que llevaban una mutación del prompt de sistema: 21 de 61 antes, 0 de 90 después.
• Turnos consecutivos que fueron estrictamente de solo agregado tras la corrección: 31 de 31.
• Re-prefills del lado del servidor por encima de 20k tokens: pasaron de 1–2 por hora a 0.

Nuevas pruebas sobre upstream gentle-shell main

Volvimos a comprobar upstream gentle-shell main en aa2c0389 durante la ejecución en producción real y publicamos los resultados en #1367 el 2026-10-07. Ocho subagentes enviaron 344 solicitudes con un prompt de sistema por sesión; 336 de 336 pares consecutivos fueron de solo agregado, y los hits de la caché de prefijo por sesión fueron de 95.5–98.4%. El bloque de todo no apareció en ningún prompt de sistema, y el problema no se repitió. Para mayor precisión: aa2c0389 todavía agrega el bloque de todo en before_agent_start, y su disparador (tareas pendientes abiertas más un prompt de usuario nuevo) no se produjo en esta ejecución. El issue sigue abierto para que su autor y los mantenedores decidan.

Nueva prueba el 2026-10-10: el problema sigue presente en upstream main, y hubo que aplicar la corrección. Volvimos a probar gentle-shell main en 43541a0d con una prueba que ejercita los hooks públicos de la extensión de todo y con una sesión de pi en vivo contra oMLX. Upstream main todavía agrega ## Todo list y su contador de obsolescencia al prompt de sistema en before_agent_start (extensions/gentle-todo.ts). En una sesión con tareas pendientes abiertas, cada prompt de usuario nuevo cambiaba el prompt de sistema: aparecía el bloque y luego el contador pasaba de stale: 2 a 3 y 4. En vivo, la sesión produjo 4 mensajes de sistema, 3 de ellos actualizaciones "Updated system prompt section" que llevaban el bloque de todo. Reanudar una sesión también agregó un bloque de todo (+515 caracteres) que el prompt de sistema inicial nunca tuvo. El cambio reciente del recordatorio (#1924) agrega un mensaje de recordatorio local a la solicitud, que es compatible con la caché, pero el bloque en el prompt de sistema permanece.

El disparador es la sesión principal (padre). Los subagentes y los trabajos en segundo plano de gentle-shell no cargan el hook de todo, por lo que la ventana anterior, solo con subagentes, no mostró cambios. Cada actualización se envía como un mensaje de sistema, y la plantilla de chat de Qwen acepta un mensaje de sistema solo al principio, por lo que se pliega en la cabeza del sistema justo después del prompt base (unos 4,050 tokens). Todo lo que viene después de ese punto debe volver a pasar por prefill. El log de oMLX de la ejecución en vivo lo muestra:

La sesión era corta, por lo que aquí cada ruptura costó solo unos cientos de tokens. En una sesión de 100k tokens, la misma ruptura vuelve a hacer prefill de casi toda la conversación en cada prompt del usuario mientras haya tareas pendientes abiertas.

La lista de tareas pendientes tiene que seguir cambiando; la cuestión es dónde va el cambio. La corrección no congela el estado de todo. Agrega las actualizaciones de todo al final de la conversación, como mensajes ocultos enviados solo cuando la lista cambia realmente, en lugar de reescribir el prompt de sistema, de modo que se preserva el prefijo en caché. El recordatorio de obsolescencia se envía una sola vez, sin contador. Rebasamos la corrección sobre 43541a0d (conserva el recordatorio de #1924). Con ella, cada solicitud reutilizó su prefijo completo salvo el re-renderizado esperado de la respuesta anterior, y las 63 pruebas de todo pasan. También superó una revisión independiente sin hallazgos bloqueantes. La nueva prueba, la tabla de caché y la corrección rebasada (rama fix/todo-prompt-cache-1367) se publicaron en #1367 el 2026-10-10, corrigiendo el comentario del 2026-10-07 mencionado arriba.

Estado al 2026-10-11. Upstream main en d42264b4 todavía agrega el bloque de todo al prompt de sistema en before_agent_start (appendSystemPromptOnce en extensions/gentle-todo.ts). La rama de la corrección es un solo commit sobre 43541a0d. El mismo parche se aplica sin cambios sobre 563fede6, donde se ejecuta en el uso diario. Se rebasará sobre el main actual antes de abrir un pull request.

Subagentes y trabajos en segundo plano

En upstream main, el disparador es la sesión padre: los subagentes y los trabajos en segundo plano se ejecutan con GENTLE_PI_AGENTS_CHILD=1 y no cargan el hook de todo. Para comprobar todo el harness con la corrección, ejecutamos una build de gentle-shell que lleva el mismo parche (git patch-id idéntico al de 4b929257, aplicado sobre upstream 563fede6) en modo RPC de pi contra el servidor en ejecución. Una sola sesión padre ejecutó una lista de todo, un subagente en primer plano, un subagente en segundo plano y su despertar, un trabajo en segundo plano y su aviso, y dos prompts de seguimiento.

• El padre conservó un solo mensaje de sistema, el del inicio de la sesión. Las instantáneas de todo (4) y los avisos de subagentes y de trabajos viajaron como mensajes de conversación personalizados.
• Cada sesión hija conservó un solo mensaje de sistema.
• De 18 solicitudes, 11 reutilizaron el prefijo en caché completo y 2 fueron los arranques en frío del padre y del primer hijo. El segundo hijo arrancó desde un límite de bloque de 2048 tokens de la caché del primer hijo, como se esperaba. Las otras 4 fueron solicitudes del padre que divergieron en un límite de bloque; ninguna fue causada por un cambio del prompt de sistema.

Avisos del harness y conservación del razonamiento

Esas 4 divergencias del padre ocurrieron justo después de avisos del harness: una actualización de todo, un resultado o un despertar de subagente, un aviso de trabajo. pi los envía como mensajes con rol de usuario, por lo que la plantilla de Qwen trata cada uno como una nueva consulta del usuario. Con preserve_thinking: false, la plantilla elimina entonces el razonamiento del segmento anterior, el prompt se acorta y el prefill se reinicia en el primer mensaje del asistente de ese segmento. Del lado del servidor, preserve_thinking: true elimina la pérdida: en el mismo escenario, 11 de 11 solicitudes del padre reutilizaron su prefijo completo, y los tokens sin caché bajaron de 6,208 a 1,803 (medición). Esto es útil para los autores de harness. Un aviso que llega como mensaje con rol de usuario es un límite de caché para las plantillas que eliminan el razonamiento en la última consulta del usuario, por lo que importa con qué frecuencia se envían los avisos.

Otros hallazgos del harness

Ejecutar el harness y el servidor juntos durante la ejecución en producción real (fork.5) sacó a la luz más cambios de prompt que ninguno de los dos lados muestra por sí solo. Pertenecen a gentle-shell, no a oMLX. Los dos primeros ya están planteados en #1367: la directiva YOLO como pregunta de seguimiento (relacionada con #1029, el estado volátil de RDD en el prompt de sistema), y la alternancia del anexo de memoria en el comentario del 2026-10-07. Los dos últimos todavía no están reportados. En aa2c0389 el bloque de todo todavía se inyecta en el prompt de sistema en before_agent_start; no se activó en esta ventana porque no llegó ningún prompt de usuario nuevo mientras había tareas pendientes abiertas.

1. Activar el modo YOLO de gentle-shell inyecta su directiva en el prompt de sistema. En la sesión orquestadora (2026-10-06 22:53, antes de esta ventana) eso costó un re-prefill de 34,379 tokens: 111.9 s de prefill, frente a alrededor de 1.6 s del siguiente turno con hit de caché.
2. Un apéndice de memoria de Engram se agregó y se quitó del prompt de sistema de la segunda sesión dos veces, y se alternó una vez en el del orquestador. Cada alternancia invalida la caché desde ese punto en adelante.
3. El rol gentle-ai-worker carecía de la herramienta nativa agent_browser, mientras que la guardia del harness la exige para el trabajo con navegador.
4. Los workers de squad lanzados por una extensión de terceros no usaron el modelo local fijado en el perfil. Arrancaron con un modelo en la nube y fallaron por falta de credenciales.

Por qué importa para proyectos de harness como gentle-shell

• La caché de prefijo y de KV permite que tanto los servidores locales (oMLX, llama.cpp, vLLM, MLX) como las API alojadas mantengan asequibles las sesiones largas de agentes. Un harness que reescribe un prefijo anterior puede aumentar la entrada no cacheada y la latencia. El impacto depende de las reglas de caché, los precios y la carga de cada backend.
• Las pruebas habituales del comportamiento de todo no detectaron esta interacción. Una invariante de estabilidad del prompt puede detectar la reescritura sin servidor; las mediciones de extremo a extremo son necesarias para cuantificar su impacto en caché y latencia.
• El mismo ciclo separó las causas con claridad: una estaba en el harness (corregida en una rama de gentle-shell; todavía presente en upstream main el 2026-10-10 y el 2026-10-11), dos estaban en el servidor (A1, A2) y el resto eran esperadas (compactación, turnos reales del usuario).

Una propuesta para gentle-shell

• Una prueba de invariante de estabilidad del prompt. Ejecutar N turnos a través del harness con fakes y comprobar que cada solicitud renderizada es una extensión estricta, por prefijo, de la anterior, salvo en los límites declarados (un mensaje real del usuario, una compactación). La corrección de #1367 ya incluye la versión acotada de esto para la herramienta de todo. Se podría generalizar a cada extensión que toca el prompt de sistema (estado de RDD, directiva YOLO, memoria).
• Una comprobación opcional de extremo a extremo contra un servidor local. Ejecutar una sesión guionada contra un servidor local compatible con OpenAI que informe los tokens en caché (oMLX lo hace, mediante usage.prompt_tokens_details.cached_tokens). Señalar cualquier turno cuyo conteo de tokens en caché caiga por debajo de la longitud del prompt anterior.
• Un modo grabador. Un grabador de payloads opcional hace reproducible este tipo de diagnóstico para los usuarios que informan "se puso lento".

Hallazgos abiertos

La equidad del decode no cubre los prompts multimodales

Cualquier solicitud con una imagen en cualquier parte de su historial lleva vlm_inputs_embeds y hace prefill en el bucle externo síncrono. Eso ocurre incluso cuando todas las imágenes ya están dentro del prefijo en caché restaurado y el sufijo no cacheado es texto puro. Ambas ramas por chunks requieren vlm_embeds is None, por lo que el decode concurrente se congela durante todo el prefill: se observaron 25–46 s, y 155 s en prefills en frío de 43k. La corrección ya está construida como parte del ciclo de pausa y reanudación (C6, opt-in OMLX_MEDIA_TEXT_SUFFIX_CHUNKED). Envía un sufijo solo de texto que sigue a una última imagen en caché por la ruta por chunks, tras comprobar que las posiciones del sufijo son t + rope_delta en cada plano mRoPE. Las pruebas con un modelo diminuto muestran una salida idéntica con la ruta activada y desactivada. Su efecto sobre los congelamientos del decode todavía no se ha medido en hardware real.

Atención del decode TurboQuant en profundidad

Una regresión sobre 975 solicitudes de una sola fila da unos 250–295 ns por token de contexto por ciclo de MTP, frente a aproximadamente 32 ns para una lectura de KV pura con el tamaño de KV de este modelo. La intersección es de 70–75 ms frente a un roofline de pesos cercano a 30 ms. Son estimaciones a partir de logs. Todavía no hemos hecho perfilado a nivel de kernel.

La verificación de MTP de profundidad 1 usa el qmm estándar

La verificación de profundidad 1 (M=2) se ejecuta en el 97.5% de los ciclos, y ninguna ruta de verify-qmm acepta M=2: las rutas cubren 3–6, 4–8 y 7–24. A partir de esto estimamos 10–20 ms por ciclo. MTP sigue siendo positivo en neto en todos los tramos de contexto (1.3–1.45×).

Cómo se validó

Estado de la evidencia. Las cifras de benchmarks, los conteos de tráfico, los resultados de las suites de pruebas y la finalización del piloto incluidos en este informe son reportados por el autor, no una reproducción independiente. Una auditoría de referencias comprobó los destinos de los enlaces publicados, las anclas internas, el código y las pruebas disponibles, la aritmética y la relación entre los commits medidos y publicados. Que un enlace esté disponible o exista el código de una prueba no demuestra que una ejecución haya pasado. Esta página no enlaza actualmente un archivo inmutable con los logs primarios, los resultados y la configuración exacta de cada medición, ni una auditoría independiente del contenido de la wiki. Las salidas no idénticas de PR1 y el fallback de PR2 no ejercitado en hardware siguen siendo limitaciones; los enlaces a ramas pueden cambiar, por lo que deben usarse los hashes de commits como evidencia fija.

• Pruebas primero. Cada comportamiento vino con una prueba de regresión que fallaba antes del cambio y pasaba después. La suite completa del fork tiene 17,063 aprobadas y 439 omitidas, más tres fallas solo del entorno (un modelo de recurso local sin plantilla de chat).
• Revisiones independientes. Cada slice se revisó por separado, con cuatro lentes de revisión en los slices de alto riesgo. Los hallazgos se incorporaron como pequeños commits de seguimiento, por ejemplo la degradación controlada cuando un tokenizer VLM no tiene encode.
• Benchmarks contra upstream. El harness de premisas ejecutó servidores de upstream y del fork de forma aislada, y comprobó que la app en vivo estuviera inactiva. Señaló las ejecuciones contaminadas, las descartó y las volvió a ejecutar.
• Reproducción de tráfico registrado. Un grabador del lado del cliente captura los payloads exactos del proveedor, y un reproductor los reenvía en orden a un servidor aislado para medir la reutilización por build.

Código fuente y referencias a commits

Cada commit y rama que se nombra en este informe enlaza al fork en GitHub, e-Evolution/omlx (las referencias de gentle-shell enlazan a e-Evolution/gentle-shell). Los commits de upstream se pueden ver desde el fork con los mismos hashes. Las ramas de los PR son fix/turboquant-padded-batched-decode (PR1) y fix/turboquant-restored-prefix-prefill (PR2).

Las ramas del fork se publicaron el 2026-10-11. Antes de publicarlas se reemplazaron las rutas locales de la máquina en los valores por defecto de los benchmarks, en un fixture de test y en un docstring (directorio de salida, nombre del volumen de caché). La comparación de los 17 pares de árboles Git medidos y publicados no encontró diferencias bajo omlx/. Las diferencias se limitan a rutas por defecto de los benchmarks, documentación y ejemplos de apoyo, el fixture de rutas y la referencia del docstring de C7. Por lo tanto, los árboles completos no son idénticos byte a byte; la reproducción requiere configurar explícitamente las rutas locales. Esto corrobora la continuidad del código fuente, no las mediciones históricas. Los hashes de los commits cambiaron. El informe muestra los hashes publicados; la tabla relaciona cada uno con el hash que se midió, que es el que aparece en los logs. Al pasar el cursor sobre un hash publicado se ve la misma relación. El commit anterior de PR1, 61bd8a06, reemplazado por la rama rebasada, se conserva con el tag report/61bd8a06.

Contribución propuesta

Para oMLX

Nos gustaría enviarlos a upstream como pull requests pequeños, cada uno con sus propias pruebas de regresión y cifras de antes y después en el mismo hardware, siguiendo docs/CONTRIBUTING.md. Upstream dirige las propuestas de funcionalidades a GitHub Discussions > Ideas, y los issues en blanco están deshabilitados, por lo que la propuesta se publicó como la discusión de Ideas #4440 (2026-10-11). Las dos correcciones de TurboQuant, PR1 y PR2, son correcciones de bugs de menos de 1,000 líneas modificadas, por lo que se abrieron directamente el mismo día: PR1 como #4441 y PR2 como #4442. El 2026-10-12 el mantenedor integró PR2 como #4442, con un ajuste posterior del dtype denso cuando ninguna capa KV es simple y el embedding está cuantizado, y cerró PR1 en favor de #4453, que extiende el kernel de #4408 para tomar el relleno a la izquierda de cada fila y nos incluye como coautores. El ciclo de pausa y reanudación supera las 1,000 líneas modificadas y agrega un subsistema, por lo que primero se presentó para recibir comentarios en #4440; el 2026-10-12 su stack se abrió como doce pull requests, de #4478 (listo para revisión) a #4489 (borradores). Cada slice indica su dependencia y su orden de merge. El orden es una propuesta y lo adaptaremos a sus preferencias.

Cada rama de abajo está rebasada sobre upstream main 013bc3f3 (2026-10-10, MLX 0.32.3, mlx-vlm 0.7.7). Sobre esa base, el comando de CI (-m "not slow and not integration" -n 3 --dist loadgroup, Python 3.11, un venv con las versiones fijadas de main) da 16,928 aprobadas en main, 16,956 con PR1 (+28 pruebas) y 16,944 con PR2 (+16), con las mismas 3 fallas solo del entorno (test_gemma4_rendering.py). Antes de abrirlos, PR1 y PR2 también se comprobaron contra el main más reciente e02ae514 (2026-10-11): ambos se integran sin conflictos, y el comando de CI da 16,938 aprobadas en main, 16,966 con PR1 y 16,954 con PR2, con las mismas 3 fallas. Todo el stack se reconstruyó sobre la misma base a partir del fork, cada slice de P-a a S9, con la condición memory_scheduling (G) antes de S4; cada slice se aplica sobre el anterior, y sus pruebas específicas y el comando de CI pasan en su punta (salvo dos pruebas sensibles a la carga que pasan por sí solas). Para los pull requests, el stack se rebasó sobre main f3ad34d2 (2026-10-12) y, siguiendo #4396 de upstream, sus dos interruptores solo por variable de entorno pasaron a ser configuraciones (memory.abort_single_victim, scheduler.media_text_suffix_chunked) y se quitó el control de prueba para pausas forzadas. El comando de CI da 17,119 aprobadas en ese main y de 17,175 (P-a) a 17,580 (S9) en las puntas de los slices, con las mismas 3 fallas; una prueba de cluster sensible a la carga también falló en S2 y S4 y pasa por sí sola 3/3 en ambos.

Alrededor de dos tercios de las líneas modificadas del ciclo son pruebas. Para S1–S9 y G, los conteos por slice de la tabla siguiente suman 8,632 líneas de prueba de 12,961 (67%); con los prerrequisitos P-a y P-b, 11,658 de 17,652 (66%). El scheduler es concurrente (el hilo de MLX, el enforcer de memoria y el escritor del SSD se intercalan), por lo que cada caso límite encontrado con el modelo real tiene una prueba de regresión sobre el scheduler y el enforcer reales en lugar de sobre fakes. Por eso se divide en pull requests encadenados, cada uno con sus propias pruebas.

Los conteos de líneas son adiciones más eliminaciones de cada slice frente al slice anterior, sobre main 013bc3f3. "Planificación de memoria" significa desactivada a menos que se fije un techo de memoria explícito o memory_scheduling=on. G agrega esa condición antes de que cualquier ruta la lea, y S4, S7 y S8 la consultan desde su primer commit, por lo que, con todas las opciones desactivadas, cada prefijo del stack se comporta como main en estas rutas; cada slice condicionado tiene pruebas que lo ejercitan con la condición desactivada y esperan el comportamiento de main. La evidencia de C7 sobre c0b1056b (revalidación) cubre P-b, S1–S3, G y S6–S9, la ejecución de identidad con MTP desactivado cubre S2, la ejecución de nunca cabe cubre S4, y S5 solo tiene pruebas unitarias y de identidad con un modelo diminuto. La reconstrucción hizo cherry-pick de los commits del fork en el orden de los slices con resoluciones mecánicas; la única prueba que usaba el archivo de valores por defecto del fork (la prueba de estado de administración de G) ahora fija el modo en settings.json, y una corrección de fixture de prueba para upstream #4312 pasó a S6, cuyas pruebas la necesitan. Estos commits del fork no están en ningún pull request: los commits de empaquetado (paquete de valores por defecto, eliminación de la condición, --allow-pin-mismatch), la capa del archivo de valores por defecto y el lector compartido de variables de entorno on/off que la acompaña, el harness benchmarks/unattended (enlazado solo como reproducción) y la prueba del lado del fork que combina PR2 con el park de prefill (llegará cuando ambos estén en main).

Propuestas posteriores y separadas para oMLX

Reportes de bugs de oMLX que presentaríamos (o comentaríamos)

• El decode por lotes de TurboQuant con relleno a la izquierda atiende sobre columnas de relleno (proporción de normas de la fila corta de 0.32 en pruebas sintéticas) y es lento (alrededor de 1.5 tok/s por fila con B=3 sobre 25aebb3e), con un caso de reproducción; PR1 es la corrección. La salida degenerada y los abortos se observaron solo sobre b7c7929e con el runtime de la app v0.7.0. Relacionados: #4110, #3767, #2784.
• Prefill de sufijo lento tras una restauración desde la caché SSD paginada de un prefijo TurboQuant (2.4× un prefill en frío de las mismas posiciones sobre c0b1056b); PR2 es la corrección. Relacionados: #1842, #3933.
• Equidad del decode omitida para prompts multimodales. Relacionado: #3209.
• La salida de una sola solicitud con Lightning MTP no es reproducible bit a bit entre ejecuciones. Divergió en 1 de 3 ejecuciones en upstream.
• Contexto de A1 y A2 agregado a los hilos existentes (#3608, #1966, #3378, #900, #1003) en lugar de abrir issues nuevos.

Antes de cada PR de oMLX vamos a

• rebasar sobre el main actual (013bc3f3 en el último rebase, 2026-10-10: MLX 0.32.3, mlx-vlm 0.7.7);
• ejecutar el comando de CI: python -m pytest tests/ -m "not slow and not integration" -n 3 --dist loadgroup con Python 3.11, más Black y Ruff a 88 columnas;
• volver a ejecutar el benchmark correspondiente contra main indicando el número de ejecuciones.

Para gentle-shell

gentle-shell exige un issue con status:approved antes de un pull request. #1367 está abierto con status:needs-review, y pedimos su aprobación para que la corrección pueda entrar como pull request, o integrarse en otro cambio si los mantenedores lo prefieren.