@hoilab/ada-cli 0.84.22 → 0.85.1

package/docs/models.md

@@ -1,6 +1,6 @@
 # Custom Models
 
-Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.pi/agent/models.json`.
+Add custom providers and models (Ollama, vLLM, LM Studio, proxies) via `~/.ada/agent/models.json`.
 
 ## Table of Contents
 
@@ -34,9 +34,9 @@ For local models (Ollama, LM Studio, vLLM), only `id` is required per model:
 }
 ```
 
-The `apiKey` value is a placeholder because Ollama ignores it. pi still treats models as requiring auth before they appear in `/model`, so keyless local servers should keep a dummy value, save a key for that provider with `/login`, or pass `--api-key` when selecting the model.
+The `apiKey` value is a placeholder because Ollama ignores it. Ada still treats models as requiring auth before they appear in `/model`, so keyless local servers should keep a dummy value, save a key for that provider with `/login`, or pass `--api-key` when selecting the model.
 
-Some OpenAI-compatible servers do not understand the `developer` role used for reasoning-capable models. For those providers, set `compat.supportsDeveloperRole` to `false` so pi sends the system prompt as a `system` message instead. If the server also does not support `reasoning_effort`, set `compat.supportsReasoningEffort` to `false` too.
+Some OpenAI-compatible servers do not understand the `developer` role used for reasoning-capable models. For those providers, set `compat.supportsDeveloperRole` to `false` so Ada sends the system prompt as a `system` message instead. If the server also does not support `reasoning_effort`, set `compat.supportsReasoningEffort` to `false` too.
 
 You can set `compat` at the provider level to apply to all models, or at the model level to override a specific model. This commonly applies to Ollama, vLLM, SGLang, and similar OpenAI-compatible servers.
 
@@ -169,7 +169,7 @@ The `apiKey` and `headers` fields support command execution, environment interpo
   "apiKey": "sk-..."
   ```
 
-For `models.json`, shell commands are resolved at request time. pi intentionally does not apply built-in TTL, stale reuse, or recovery logic for arbitrary commands. Different commands need different caching and failure strategies, and pi cannot infer the right one.
+For `models.json`, shell commands are resolved at request time. Ada intentionally does not apply built-in TTL, stale reuse, or recovery logic for arbitrary commands. Different commands need different caching and failure strategies, and Ada cannot infer the right one.
 
 If your command is slow, expensive, rate-limited, or should keep using a previous value on transient failures, wrap it in your own script or command that implements the caching or TTL behavior you want.
 
@@ -202,7 +202,7 @@ If your command is slow, expensive, rate-limited, or should keep using a previou
 | `name` | No | `id` | Human-readable model label. Used for matching (`--model` patterns) and shown as secondary model detail text. |
 | `api` | No | provider's `api` | Override provider's API for this model |
 | `reasoning` | No | `false` | Supports extended thinking |
-| `thinkingLevelMap` | No | omitted | Maps pi thinking levels to provider values and marks unsupported levels (see below) |
+| `thinkingLevelMap` | No | omitted | Maps Ada thinking levels to provider values and marks unsupported levels (see below) |
 | `input` | No | `["text"]` | Input types: `["text"]` or `["text", "image"]` |
 | `contextWindow` | No | `128000` | Context window size in tokens |
 | `maxTokens` | No | `16384` | Maximum output tokens |
@@ -238,7 +238,7 @@ Current behavior:
 
 ### Sampling Parameters
 
-`samplingParams` is a free-form object merged verbatim into every request body for the model, after the fields pi sets itself, so its keys win. Use it to send sampling parameters pi does not model — including server-specific ones like llama.cpp's `min_p` or vLLM's `top_k`:
+`samplingParams` is a free-form object merged verbatim into every request body for the model, after the fields Ada sets itself, so its keys win. Use it to send sampling parameters Ada does not model — including server-specific ones like llama.cpp's `min_p` or vLLM's `top_k`:
 
 ```json
 {
@@ -252,13 +252,13 @@ Current behavior:
 }
 ```
 
-Only OpenAI-compatible APIs apply it (`openai-completions`, `openai-responses`, `azure-openai-responses`); other APIs ignore it. Keys override pi's named request fields (for example a `temperature` key here beats the request-level temperature), so prefer it as the single source of sampling truth for a model. In `modelOverrides`, `samplingParams` merges per key with the base model's value.
+Only OpenAI-compatible APIs apply it (`openai-completions`, `openai-responses`, `azure-openai-responses`); other APIs ignore it. Keys override Ada's named request fields (for example a `temperature` key here beats the request-level temperature), so prefer it as the single source of sampling truth for a model. In `modelOverrides`, `samplingParams` merges per key with the base model's value.
 
 A constant thinking-token cap can go here too, but it will not follow `thinkingBudgets` or leave room for the answer. Prefer `compat.thinkingTokenBudgetField` (or the `supportsThinkingTokenBudget` alias) for that.
 
 ### Thinking Level Map
 
-Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are pi thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Maps may contain holes; for example, a model can expose `high` and `max` without exposing `xhigh`.
+Use `thinkingLevelMap` on a model to describe model-specific thinking controls. Keys are Ada thinking levels: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`. Maps may contain holes; for example, a model can expose `high` and `max` without exposing `xhigh`.
 
 Values are tristate:
 
@@ -390,7 +390,7 @@ Behavior notes:
 
 For providers or proxies using `api: "anthropic-messages"`, use `compat` to control Anthropic-specific request compatibility.
 
-By default pi sends per-tool `eager_input_streaming: true`. If a proxy or Anthropic-compatible backend rejects that field, set `supportsEagerToolInputStreaming` to `false`. Pi will omit `tools[].eager_input_streaming` and send the legacy `fine-grained-tool-streaming-2025-05-14` beta header for tool-enabled requests instead.
+By default Ada sends per-tool `eager_input_streaming: true`. If a proxy or Anthropic-compatible backend rejects that field, set `supportsEagerToolInputStreaming` to `false`. Ada will omit `tools[].eager_input_streaming` and send the legacy `fine-grained-tool-streaming-2025-05-14` beta header for tool-enabled requests instead.
 
 Some Anthropic models require adaptive thinking (`thinking.type: "adaptive"` plus `output_config.effort`) instead of the legacy budget-based thinking payload. Built-in models set this automatically. For custom providers or aliases that route to those models, set `forceAdaptiveThinking` to `true`.
 
@@ -462,15 +462,15 @@ For providers with partial OpenAI compatibility, use the `compat` field.
 | `supportsDeveloperRole` | Use `developer` vs `system` role |
 | `supportsReasoningEffort` | Support for `reasoning_effort` parameter |
 | `supportsUsageInStreaming` | Supports `stream_options: { include_usage: true }` (default: `true`) |
-| `supportsFinishReason` | Whether streamed responses include `finish_reason`. When `false`, pi infers `stop` or `toolUse` when the stream ends. Default: `true`. |
+| `supportsFinishReason` | Whether streamed responses include `finish_reason`. When `false`, Ada infers `stop` or `toolUse` when the stream ends. Default: `true`. |
 | `maxTokensField` | Use `max_completion_tokens` or `max_tokens` |
 | `requiresToolResultName` | Include `name` on tool result messages |
 | `requiresAssistantAfterToolResult` | Insert an assistant message before a user message after tool results |
 | `requiresThinkingAsText` | Convert thinking blocks to plain text |
 | `requiresReasoningContentOnAssistantMessages` | Include empty `reasoning_content` on all replayed assistant messages when reasoning is enabled |
 | `thinkingFormat` | Use `reasoning_effort`, `openrouter`, `deepseek`, `together`, `baseten`, `zai`, `qwen`, `chat-template`, or `qwen-chat-template` thinking parameters |
-| `chatTemplateKwargs` | `chat_template_kwargs` values for `thinkingFormat: "chat-template"`; use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for pi-controlled thinking values |
-| `chatTemplateArgs` | `chat_template_args` values for `thinkingFormat: "baseten"`; use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for pi-controlled thinking values |
+| `chatTemplateKwargs` | `chat_template_kwargs` values for `thinkingFormat: "chat-template"`; use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for Ada-controlled thinking values |
+| `chatTemplateArgs` | `chat_template_args` values for `thinkingFormat: "baseten"`; use `{ "$var": "thinking.enabled" }`, `{ "$var": "thinking.effort" }`, or `{ "$var": "thinking.budget" }` for Ada-controlled thinking values |
 | `thinkingTokenBudgetField` | Top-level request field used to cap reasoning tokens from `thinkingBudgets`, clamped so at least 1024 tokens remain for the answer. `"thinking_token_budget"` (vLLM), `"thinking_budget"` (Qwen/DashScope/SGLang), `"thinking_budget_tokens"` (llama.cpp). Off by default; not set on the generated catalog. |
 | `supportsThinkingTokenBudget` | Alias for `thinkingTokenBudgetField: "thinking_token_budget"` (vLLM). Prefer `thinkingTokenBudgetField`. Default: `false`. |
 | `cacheControlFormat` | Use Anthropic-style `cache_control` markers on the system prompt, last tool definition, and last user, assistant, or tool-result text content. Currently only `anthropic` is supported. |

package/docs/modules-infraestructura.md

@@ -0,0 +1,115 @@
+# Infraestructura
+
+Módulos de soporte que hacen que el CLI sobreviva a sesiones largas, procesos concurrentes y equipos: brokers por proyecto, terminal robusta, recolección de basura del almacenamiento, perfiles multi-workspace y un broker de credenciales compartidas.
+
+## Broker de daemons — un daemon vivo como máximo por proyecto
+Evita que dos `ada` en el mismo directorio arranquen daemons duplicados (LSP, watchers) que pelean por puertos y ficheros.
+**Activa**: automático al solicitar un daemon vía `getBroker(projectRoot)`; inspección con `ada ps`.
+**Garantiza**:
+- Segundo proceso reutiliza el daemon del primero (Map en memoria + heartbeat).
+- Un daemon sin latido más de 60 s se considera caducado (`DEFAULT_HEARTBEAT_TTL_MS`).
+- Verificación de pid por `startId` para no matar un pid reciclado.
+- `ada ps` en dos formatos: tabla humana (narrando huérfanos) y JSON para scripts/tests.
+- API sin sockets ni locks de fichero; contratos de `ps`/`reap` estables si se añade persistencia futura.
+**No garantiza**:
+- No persiste entre procesos (si hace falta, sería un journal JSONL encima, sin cambiar los contratos).
+**Código**: `src/core/broker/{broker,ps,index}.ts`
+**Test**: `test/broker-ps.test.ts`
+
+## Terminal robusta — output del agente que no tumba el proceso
+Protege el TUI/host PTY cuando un agente atascado vomita megabytes o repite la misma línea miles de veces.
+**Activa**: automática en el camino de escritura de output (`TerminalRunner`); no requiere flags.
+**Garantiza**:
+- Techo de backlog de 64 MiB con descarte FIFO del frente y marcado `truncado` para avisar «[output truncado — se descartaron X bytes del inicio]»; `excedeLimite()` es O(1).
+- Chunking ConPTY: payloads grandes fragmentados en ventanas de 4 KiB para backpressure por chunk y evitar bloqueos del canal PTY.
+- LoopWatchdog: ventana de 1 KiB hasheada (SHA-256) por chunk; repeticiones idénticas consecutivas disparan `onLoopDetected(hash, count)` y opcionalmente jitter delay para frenar al productor sin perder datos.
+- Los tests ejercitan los tres estados con un stream sintético de 1000 líneas idénticas: ok / truncado / bucle-detectado.
+**No garantiza**:
+- El contenido descartado por FIFO no se recupera (solo se reporta cuánto se perdió).
+**Código**: `src/core/terminal/{backlog-guard,conpty,loop-watchdog,runner}.ts`
+**Test**: `test/terminal-robustez.test.ts`
+
+## GC de almacenamiento — blobs huérfanos, sesiones frías y journals limpios
+Recolección de basura productiva sobre el agentDir: purga blobs no referenciados, gzippea sesiones viejas y reconcilia contadores.
+**Activa**: comando/mantenimiento vía `ejecutarGC(opts)` (patrón builtin `ada gc`; wiring documentado en el módulo).
+**Garantiza**:
+- GC de blobs por referencias: recorre sessions buscando sha256 referenciados y purga entradas no referenciadas tras una gracia (7 días por defecto), incluida la caché de disco `<agentDir>/blobs/<sha256>`.
+- Archivo frío: sesiones > N días sin actividad se comprueban a gzip en `cold/` dejando un tombstone JSON (`_cold`, `_archivedAt`); re-hidratación disponible (`rehidratarSesion`) detectando `_cold`.
+- Reconciliación stats/history: re-cuenta sessions/index.json vs filesystem (número, tamaño total, huérfanas) y reporta divergencias.
+- WAL checkpoint TRUNCATE para SQLite en modo WAL (sessions.db, audit.db); best-effort, no falla si no hay fichero o SQLite.
+- Breaker-lock con creación atómica O_EXCL: evita dos GC concurrentes sobre el mismo agentDir (reintento cada 500 ms hasta agotar intentos).
+**No garantiza**:
+- La re-hidratación depende de que el loader detecte el tombstone `_cold`.
+- WAL es best-effort: con JSONL puro es un no-op documentado.
+**Código**: `src/core/gc/{blobs-gc,archivo-frio,reconciliacion,wal,lock,index}.ts`
+**Test**: `test/gc-almacenamiento.test.ts`
+
+## Perfiles multi-workspace — varios workspaces en una sola sesión
+Permite abrir una sesión con perfil y directorios adicionales resueltos ANTES de cualquier carga de config desde disco (pre-import, 0 hunks).
+**Activa**: flags `--profile <nombre>`, `--alias <nombre>`, `--add-dir <dir>` en la línea de comandos.
+**Garantiza**:
+- Lookahead por argv crudo antes de que el parser principal toque `getAgentDir()`.
+- I/O perezoso: solo lee `~/.ada/profiles/<name>.json` si hay `--profile` explícito y no es `default`.
+- `contextosDeTrabajo(perfil, cwd)` devuelve cwd + add-dirs validados para pasar a AgentSession / resource-loader.
+- `FLAG_TABLE` como fuente única de verdad de qué flags consumen valor, consultada tanto por el pre-parser como por el parser principal (patrón espejo omp cli/flag-tables.ts).
+**No garantiza**:
+- Nada más allá de lo declarado en los perfiles: no valida contenido arbitrario de config.
+**Código**: `src/core/perfiles/{resolver,tipos,index}.ts`
+**Test**: `test/perfiles.test.ts`
+
+## Config viva — settings por ruta y valores `!cmd` que se recuperan
+Config que responde al directorio actual y a fallos transitorios, en vez de congelar resultados muertos para siempre.
+**Activa**: capability `"config-viva"` sobre el registro de capabilities (`loadCapability(CAPABILITY_CONFIG_VIVA)` tras registrar su provider); formato opt-in por clave en settings.
+**Garantiza**:
+- Ámbito por prefijo de ruta (C05): `enabledModels` acepta entradas `{ "pathPrefix": "...", "values": [...] }`. Resolución: primera capa (proyecto antes que global) que responda gana; valor plano gana sobre entradas acotadas de su capa; entre coincidencias gana el prefijo MÁS LARGO; sin coincidencia cae a la capa siguiente. API pura, sin I/O.
+- Caché negativa con TTL (C07): éxito de `!cmd` → caché positiva permanente; fallo (undefined o throw) → caché negativa TTL 30 s por defecto; expirado, la siguiente lectura reintenta. Acaba con el «password manager bloqueado desactiva la clave para siempre».
+- Headers vivos (C07): headers `!cmd` re-resueltos como mucho cada TTL (5 s) para proveedores que rotan tokens; el punto de integración con provider-composer está documentado (requeriría hunk upstream).
+- El provider combina ámbito + caché negativa y expone SourceMeta + estadísticas de caché para contar ejecuciones reales.
+**No garantiza**:
+- Headers vivos NO están cableados en provider-composer hoy (documentado, no integrado).
+**Código**: `src/core/config-viva/{ambito,cache-negativa,headers-vivos,proveedor,index}.ts`
+**Test**: `test/config-viva.test.ts`
+
+## Carga de plugins — import paralelo determinista e invalidación cruzada
+Arranque más rápido con N plugins sin sacrificar el orden observable de registro, y recarga coherente cuando cambia un plugin.
+**Activa**: automático al cargar extensiones a través de este importador (el loader upstream no se toca); invalidación vía `invalidarRaiz(raiz)`.
+**Garantiza**:
+- Todos los imports se disparan en paralelo pero los resultados se resuelven EN EL ORDEN DE LA LISTA (el registro es determinista pase lo que pase con el I/O; «última registra gana» sigue siendo predecible).
+- Errores aislados: un plugin que falla al importar no tumba a los demás; cada error se reporta junto a su ruta.
+- Memoización por ruta: recargar con las mismas rutas reusa lo ya cargado; solo se importan los nuevos o los fallados.
+- Invalidación cruzada: registro `raíz → invalidadores`; `invalidarRaiz` ejecuta los invalidadores de esa raíz, vacía sus entradas y purga la caché global de fábricas (`clearExtensionCache`). Sobre-invalidar es seguro (una caché vacía solo fuerza re-import).
+- Importador inyectable (en producción `jiti.import`); la purga fina de módulos es un gancho configurable — si nadie registra purga, los invalidadores registrados se ejecutan igualmente.
+**No garantiza**:
+- Purga por raíz del loader upstream: no existe sin tocar `extensions/loader.ts`; la purga disponible es global.
+**Código**: `src/core/carga-plugins/{paralelo,invalidacion,index}.ts`
+**Test**: `test/carga-plugins.test.ts`
+
+## Kit higiene — código de terceros que nunca tumba el host
+Contención de daños para hooks, providers y extensiones de terceros.
+**Activa**: envolviendo llamadas a código de terceros con las utilidades del kit (`withHostGuard`, `ManagedTimers`, `raceHandlerWithTimeout`).
+**Garantiza**:
+- `withHostGuard`: una Promise de terceros nunca propaga throw al host — clasifica `error.hostGuard=true`, loggea y retorna undefined; no deja promesas colgando si el host muere.
+- `ManagedTimers`: set de timeouts/intervalos registrados con `disposeAll()` para cerrar sin dejar timers huérfanos; handles unref para no bloquear el exit del host.
+- `raceHandlerWithTimeout`: compite handler vs timer, cancela al perdedor y cubre los tres estados — éxito a tiempo, timeout→fallback, error→fallback.
+**No garantiza**:
+- No arregla bugs dentro del código de terceros: solo contiene sus efectos.
+**Código**: `src/core/higiene/{withHostGuard,managed-timers,race-handler,index}.ts`
+**Test**: `test/higiene-kit.test.ts`
+
+## Credenciales compartidas — pool con ranking, enfriamiento y broker HTTP
+Un equipo comparte credenciales de proveedor sin que cada clon de token viva en cada disco, con conmutación inteligente ante fallos.
+**Activa**: modo servidor `ada-cli serve --broker` (broker HTTP); pool + ranking usados por el gateway/pool en memoria; reposo aplicado automáticamente al leer/escribir `auth.json`.
+**Garantiza**:
+- Pool por proveedor: un 401 saca la credencial del pool; un 429 NO la saca (la cuenta sigue buena, solo ocupada) — la confusión de ambos es el error que quema cuentas sanas.
+- Pegajosidad por sesión vía `prompt_cache_key`: anclada a una credencial sana mientras dure; moverla «para equilibrar» rompería el caché de prompts y costaría más de lo que ahorra.
+- Ranking por cuota real: descarta enfriadas por rate-limit (huella del registro persistente), prioriza pegajosa disponible, luego menor uso reciente (empate → orden de declaración estable), y degrada al round-robin del pool si no hay datos — no inventa señales.
+- Enfriamiento 429 persistido: sobrevive a reinicios del broker mediante JSON atómico (temporal + rename + fsync) releído en cada arranque; en disco NUNCA hay claves, solo huellas SHA-256.
+- Broker `/v1/credential`: falla cerrado (sin bearer configurado, lanza antes de abrir el socket); comparación de bearer en tiempo constante; todo excepto `/v1/health` exige bearer; cada resolución y reporte de uso queda en el libro de sesión auditable (`core/audit/libro.ts`).
+- Cliente sin token residente: el secreto devuelto NUNCA se asigna a campo de la clase ni a disco — vive como mucho en la pila para una petición.
+- Cifrado en reposo de `<agentDir>/auth.json`: envuelve el backend upstream transformando solo el contenido dentro de la sección crítica del candado existente; clave aleatoria de 256 bits en el llavero del sistema; cabecera literal distingue claro/cifrado (nunca JSON.parse a ciegas); migración transparente en lectura (recifrado en segundo plano fuera del candado) y escritura atómica con copia de seguridad.
+**No garantiza**:
+- El pool vive en memoria: reiniciar el broker olvida bloqueos y pegajosidad (punto de extensión: persistir `estado()` en `iniciar`/`cerrar`).
+- Sin llavero disponible (CI, contenedor, Linux sin secret-service) NO se cifra auth.json — se avisa una vez y se sigue en claro; cifrar con clave en el mismo disco sería ofuscación.
+- El broker no es proxy de peticiones a proveedores: `/v1/credential` sí entrega el secreto al cliente autenticado (lo mínimo para que el cliente llame al proveedor sin tenerlo en su disco).
+**Código**: `src/core/credenciales/{pool,ranking,ratelimit,servidor,cliente,reposo}.ts`
+**Tests**: `test/pool-credenciales.test.ts`, `test/credenciales-ranking.test.ts`, `test/servidor-credenciales.test.ts`, `test/credenciales-reposo.test.ts`

package/docs/modules-motor.md

@@ -0,0 +1,160 @@
+# Módulos del motor: contexto, colaboración y medición
+
+Páginas de referencia de los subsistemas del motor que viven en `packages/coding-agent/src/core/` y no existían en upstream: gestión append-only del contexto, torre de compactación, colaboración E2E con relay cifrado, preview mid-stream de tool calls, banco medido (metaharness) y guardia de streaming.
+
+## AppendOnlyContextManager — contexto inmutable para prompt-cache
+
+Resuelve el coste invisible de reescribir historial: un solo byte distinto en la posición N invalida el prompt-cache de todo lo que va detrás (~40k tokens de re-prefill por turno reescrito).
+
+**Activa**: automático cargando la extensión `ada-cli -e packages/coding-agent/src/core/appendonly/extension.ts`. La decisión AUTO es pura y sin I/O (`appendOnlyAutoPara(baseUrl, modelo)`): se activa para deepseek (KV-cache prefix reuse documentado), baseUrl en loopback (127.0.0.0/8, localhost, ::1) y redes privadas RFC1918; NO se activa contra proveedores cloud sin garantía de prefix reuse, donde el historial inmutable solo añade restricciones. El criterio del modelo manda sobre el del baseUrl.
+
+**Garantiza**:
+- El historial SOLO crece por append: los turnos ya enviados son inmutables (clonados y congelados en profundidad; cualquier intento de mutación lanza `TypeError`).
+- `prefijoEstable()` congela un hash sha256 del prefijo; los appends posteriores no lo cambian. Solo `compactar(resumen)` lo invalida (añade una entrada resumen al final, nunca borra ni reescribe).
+- `reconstruirDesde(journal)` rehidrata el manager desde el JournalTree verificando los hashes almacenados.
+- `integrarConPruning(mgr, guard)` expone la longitud del prefijo protegido como `cachePrefixLen` al guardia de pruning: el prune solo poda en el sufijo activo.
+- Si el proveedor deja de tener prefix reuse o el historial se encoge (cambio de rama), el estado se descarta y empieza un libro nuevo.
+
+**No garantiza**:
+- No transforma mensajes: es contabilidad e inmutabilidad, no un transform del contexto.
+- No aporta nada contra proveedores cloud sin KV-reuse de prefijo estable.
+- No es builtin: requiere cargar la extensión explícitamente.
+
+**Código**: `packages/coding-agent/src/core/appendonly/append-only-context.ts`, `auto.ts`, `extension.ts`, `index.ts`
+
+**Test**: `test/appendonly.test.ts`, `test/appendonly-auto.test.ts`
+
+## Compactación — prune cache-aware, shake y handoff (/handoff /shake /fresh /drop /btw)
+
+Resuelve el crecimiento del contexto sin destruir el prompt-cache por descuido: una torre de tres plantas con reglas conservadoras y deterministas sobre qué se puede tocar.
+
+**Activa**: comandos slash `/shake`, `/drop`, `/fresh`, `/handoff`, `/btw` (extensión inline registrada por defecto desde `loadBuiltinExtensions`). Cada comando ejecuta el MOTOR REAL y devuelve uno de tres estados: «hecho» (ejecutó), «nada» (contexto válido pero nada que hacer), «uso» (falta argumento).
+
+**Garantiza**:
+- **Prune (1ª planta)**: quirúrgico sobre toolResults, solo cuando el sufijo posterior al candidato cabe en la cola barata de re-cache (por defecto 8.000 tokens, ahorro mínimo 200). Sin reloj ni TTL: la guardia rechaza y contabiliza (`rechazadosPorCache`). Copy-on-write: turnos no tocados se devuelven tal cual.
+- **Shake (2ª planta)**: colapso mecánico de turnos antiguos preservando anclas — primer mensaje user (objetivo original), toolResults referenciados por turnos vivos, cola final protegida (4.000 tokens). Los pares toolCall↔toolResult se eliminan juntos: sin referencias colgantes.
+- **Handoff (3ª planta)**: NO reescribe la historia; cierra la sesión y arranca una nueva cuyo único contexto es un resumen determinista SIN LLM (objetivo original + herramientas usadas + cola reciente) más puntero al journal arbolado de origen. `/handoff` y `/fresh` persisten bajo `<agentDir>/handoff/`.
+- **/btw**: registra notas laterales sin interrumpir; viajan con la próxima operación de contexto a la sesión nueva y se listan con `/btw` sin argumento.
+
+**No garantiza**:
+- El resumen del handoff es mecánico, no semántico: no hay LLM que sintetice.
+- Shake reescribe la historia antigua en bloque: asume que la caché se reconstruye; no respeta el prefijo ya cacheado (para eso está prune).
+- Los eventos evicted del anillo de replay y los turnos colapsados no son recuperables desde el contexto (el journal de origen sí conserva la historia completa).
+
+**Código**: `packages/coding-agent/src/core/compactacion/` (`prune.ts`, `shake.ts`, `handoff.ts`, `comandos.ts`, `extension.ts`, `tipos.ts`)
+
+**Test**: `test/compactacion.test.ts`
+
+## Colaboración — sesión E2E local, kernels persistentes y bucle autoresearch
+
+Resuelve tres huecos de trabajo iterativo: dos agentes escribiendo al mismo journal sin pisarse, estado vivo entre ejecuciones de código, y experimentación con protocolo auditable keep/discard.
+
+**Activa**: programático (clases importables); no hay comando ni extensión de usuario todavía.
+
+**Garantiza**:
+- **SesionColaborativa**: cada agente tiene su instancia apuntando al mismo fichero JSONL; ids con prefijo de agente + sufijo aleatorio nunca colisionan entre procesos ni tras reinicios. `sincronizar()` fusiona por UNIÓN de ids (nunca last-writer-wins): la fusión no pierde entradas de ningún lado; republicación atómica (temp + fsync + rename). Dos ramas hermanas bajo el mismo padre son válidas por construcción — «sin pisarse» no necesita locks.
+- **KernelJs / PoolKernels**: un contexto `node:vm` persiste entre celdas (`let`, `var` y globales sobreviven; cada celda devuelve su última expresión). Una celda fallida NO mata el kernel. El pool registra el kernel como daemon del proyecto en el broker existente (un kernel por proyecto+lenguaje; los tres estados del broker —activo/caducado/huérfano— son los del kernel, inspeccionables vía `ps`).
+- **Bucle autoresearch**: hipótesis → ejecutor INYECTABLE (los tests corren sin gastar llamadas) → parseo de líneas `METRIC nombre=valor` → registro en el journal arbolado → keep/discard sobre la métrica principal. Keep deja la leaf como punto de partida; discard hace fork hacia atrás al último resultado conservado. El journal ES la evidencia auditable.
+
+**No garantiza**:
+- SesionColaborativa no incluye relay ni cifrado: eso lo aporta el rele AG8 (siguiente sección); esta clase es la unidad que sincroniza.
+- Kernels: solo JS en proceso (`LenguajeKernel = "js"`); Py/Rb/Jl esperan subprocess runner. TTL de kernel de 60 s sin latido.
+- Autoresearch: si la salida no trae la métrica principal, no hay valor con el que decidir.
+
+**Código**: `packages/coding-agent/src/core/colaboracion/` (`sesion-colaborativa.ts`, `kernels.ts`, `autoresearch.ts`)
+
+**Test**: `test/colaboracion.test.ts`
+
+## Rele — relay SSE cifrado con secuencia y replay (colaboración E2E)
+
+Resuelve la transmisión en vivo de eventos de sesión a N suscriptores con confidencialidad real: un proceso local escucha SOLO en loopback y retransmite cada evento sellado (scrypt + AES-256-GCM, la primitiva de `share/cifrado.ts`, sin dependencias nuevas).
+
+**Activa**: programático — `ReleServidor` (servidor) y `suscribirse()` (cliente); usado como streamProxy de la colaboración CO1.
+
+**Garantiza**:
+- Token de sala de 256 bits que NUNCA viaja en argv, URLs ni logs: va en la cabecera `x-rele-token` y es TAMBIÉN la clave de sellado. Quien no lo tiene ve ruido autenticado, nada más. Comparación del token en tiempo constante.
+- Todo evento cruza la red como ciphertext autenticado; el cliente entrega eventos ya descifrados por su iterador asíncrono.
+- Secuencia monotónica por sala + anillo de replay (200 eventos): estados de sala «activa», «sin-suscriptores» (los eventos quedan en el anillo) y «cerrada» (los suscriptores terminan limpio con 410).
+- Reconexión con backoff exponencial acotado: el cliente declara `x-rele-desde-seq` y DEDUPLICA por seq (at-least-once → exactly-once).
+- 401 (token erróneo) aborta SIN reintentos; 410 (sala cerrada) termina el iterador normalmente.
+
+**No garantiza**:
+- Eventos evicted del anillo (más allá de los 200 últimos) NO se re-entregan tras un corte largo.
+- El relay es tonto: no interpreta ni persiste eventos; solo sella, numera y reenvía.
+- Escucha solo en loopback: no es un servicio multi-máquina expuesto.
+
+**Código**: `packages/coding-agent/src/core/colaboracion/rele/` (`rele-servidor.ts`, `suscriptor.ts`)
+
+**Test**: `test/rele-stream.test.ts`
+
+## TTSR preview — vista previa mid-stream de argumentos de tools
+
+Resuelve la espera ciega mientras el modelo escribe el JSON de una tool call: un observador puede ver qué lleva escrito en cada delta, sin tocar el contrato actual ni el transcript final.
+
+**Activa**: automática cargando la extensión `ada-cli -e packages/coding-agent/src/core/ttsr/index.ts` (se engancha a los eventos `toolcall_start/delta/end` vía la API pública de extensiones).
+
+**Garantiza**:
+- Captura incremental por `toolCallId`: cada delta se AÑADE, nunca se reescribe.
+- Parse parcial tolerante: un JSON cortado a la mitad devuelve lo entendible (`{ ok, valor, completo }`); jamás lanza.
+- Render recortado a líneas completas: el corte se hace en la última línea nueva, jamás se enseña media línea que cambiaría por debajo del usuario. Viewport por defecto de 24 líneas.
+- Exactly-once: cada prefijo visible se emite UNA vez por toolCallId; pedir preview sin datos nuevos devuelve `undefined`.
+- Solo lectura: el transcript final queda intacto hasta que `toolcall_end` entrega la tool_call completa.
+
+**No garantiza**:
+- Lo mostrado es un prefijo parcial: puede cambiar antes del `end`; no es compromiso del modelo.
+- Vive fuera del transcript: no altera el historial ni sustituye la tool_call final.
+
+**Código**: `packages/coding-agent/src/core/ttsr/` (`captura.ts`, `preview.ts`, `index.ts`)
+
+**Test**: `test/ttsr-preview.test.ts`
+
+## Metaharness — banco medido con percentiles y cold/warm
+
+Resuelve la autocertificación: mide con datos el comportamiento del agente contra un proveedor — aciertos Y coste (round trips, tokens, latencia TTFT/decode) — y compara dos configuraciones con números, no impresiones.
+
+**Activa**: CLI en segundo plano (una corrida tarda minutos y cuesta dinero):
+
+```
+node scripts/metaharness.mjs cargas [--salida f.json]
+node scripts/metaharness.mjs run --entrada casos.json --modelo proveedor/modelo \
+     [--salida f.json] [--timeout ms] [--casos N] [--si] [--cold-warm]
+node scripts/metaharness.mjs comparar ejecucionA.json ejecucionB.json
+```
+
+**Garantiza**:
+- Informe JSON con las métricas del banco (tres estados, ficheros temporales, normalización byte a byte — delegadas en `core/banco`, sin recopiarlas) más eficiencia por caso: vueltas, tokens entrada/salida, latencia, TTFT y decode con percentiles **p50/p95** (interpolación lineal estándar «linear», sin dependencias).
+- `--cold-warm`: dos pasadas con la MISMA instancia de ejecutor; reporta `deltaTokensPrefill` y si la caché mejoró.
+- Anti-autoengaño: si la pasada warm NO reduce el prefill, el informe lleva un AVISO explícito (o el proveedor no sirve el prompt desde caché, o el prefijo no es idéntico entre pasadas).
+- Banco de cargas mal formadas como línea base: motor puro, sin red, sin coste.
+- Ejecutor inyectable: los tests prueban que el harness MIDE con ejecutores deterministas, sin gastar una sola llamada real; el ejecutor real es el que cuesta dinero.
+- Confirmación interactiva antes de correr contra red salvo `--si`.
+
+**No garantiza**:
+- Corridas reales cuestan dinero y minutos: está pensado para segundo plano.
+- Percentiles con muestra vacía devuelven 0 y casos con timeout/error se excluyen de latencia: no inventan medidas.
+- La comparación (`comparar`) compara informes ya producidos; no orquesta corridas.
+
+**Código**: `packages/coding-agent/src/core/metaharness/` (`cli.ts`, `ejecutar.ts`, `comparar.ts`, `tipos.ts`) vía `scripts/metaharness.mjs`
+
+**Test**: `test/metaharness.test.ts`, `test/metaharness-percentiles.test.ts`
+
+## Stream-guard — vigía universal de streams con replay buffer
+
+Resuelve los streams que se cuelgan para siempre: hoy solo el WS de Codex tiene idle-timeout; cualquier otro stream (SSE del rele, MCP, subprocesos largos) puede quedar colgado indefinidamente. `vigilarStream` envuelve CUALQUIER AsyncIterator.
+
+**Activa**: programático — envolver la fuente con `vigilarStream(iterador, opciones)`; combinar con `bufferReplay` para reconexión sin pérdida.
+
+**Garantiza**:
+- **Idle**: sin eventos durante `idleTimeoutMs` (default 30.000 ms) lanza `ErrorStreamIdle` (error clasificado, no genérico), avisa por `onIdle` y cierra la fuente. Reintentar es decisión del consumidor (con replay si usó bufferReplay).
+- **In-flight**: contador global con techo (default 64 streams simultáneos, ajustable); al superarlo la primera lectura rechaza con `ErrorSaturado` hasta que alguno baje.
+- **Limpieza**: el cupo se libera y la fuente se cierra en TODAS las salidas (fin normal, error del consumidor, error del origen, idle).
+- **BufferReplay**: guarda los últimos N eventos numerados y re-entrega desde una secuencia dada con semántica Last-Event-ID de SSE (inclusive-exclusive). El rele AG8 lo usa servidor-side para atender `x-rele-desde-seq`. Seq inválida → `RangeError`; `maxEventos` inválido → error en constructor.
+
+**No garantiza**:
+- No reintenta por ti: clasifica el fallo y deja la política de reintento al consumidor.
+- Los eventos evicted del anillo de replay NO se re-entregan tras un corte mayor que el búfer.
+- El techo de streams es global del proceso: saturar un tipo de stream afecta a todos los vigilados.
+
+**Código**: `packages/coding-agent/src/core/stream-guard/` (`guardia.ts`, `replay.ts`)
+
+**Test**: `test/stream-guard.test.ts`

package/docs/modules-producto.md

@@ -0,0 +1,179 @@
+# Módulos — Producto
+
+Páginas de referencia de los módulos orientados a producto del fork Ada CLI (marketplace de plugins, registro de proveedores, memoria episódica, commits agénticos, discovery de runtimes, URIs internas, limpieza de código y consumo multi-cuenta). Audiencia: usuarios y agentes que no leen el código.
+
+## Marketplace de plugins — descubre, instala, diagnostica y configura plugins desde un catálogo
+
+Resuelve el problema de gestionar plugins de forma informada: saber qué existe (catálogo), instalarlo sin reinstalarlo dos veces, comprobar que una instalación está sana y activar/desactivar sus features.
+
+**Activa**: comandos `plugin marketplace list`, `plugin install|upgrade|uninstall <n>`, `plugin enable|disable <p> <f>`, `plugin doctor <p> [--fix]` (los hints de guardrails de `marketplace`, `upgrade`, `enable`, `disable`, `extensions` apuntan aquí). El catálogo vive en `~/.ada/marketplace.json`; un catálogo remoto se consulta cuando hay URL configurada (`ADA_MARKETPLACE_URL` u `opciones.urlRemota`) y sobreescribe entradas locales por nombre.
+
+**Garantiza**:
+- Catálogo con tres estados honestos: cargado / vacío / inaccesible (un catálogo roto es un estado, no un crash).
+- Instalación idempotente e informada: instalar lo ya instalado es un no-op declarado (`ya-instalado`), nunca una segunda instalación silenciosa; scope explícito user/project sobre el package-manager existente (npm/git/local, sin CRUD nuevo).
+- Features on/off por plugin persistidas en `~/.ada/plugin-features.json`, validadas contra lo declarado en el catálogo: no puedes activar una feature que el plugin no declara.
+- `plugin doctor`: package.json parseable, entry (`main`/`bin`) presente en disco, dependencias resueltas, features declaradas vs activas, conflictos de versión con el catálogo.
+- `--fix` solo aplica correcciones seguras y únicamente con confirmación explícita (`confirmado: true`).
+
+**No garantiza**:
+- No es destructivo ni con `--fix`: reparaciones fuera del conjunto seguro no se aplican.
+- El fetch remoto tiene timeout de 10 s y requiere URL configurada; sin ella solo hay catálogo local.
+- No valida el contenido del plugin más allá del doctor (no ejecuta auditoría de código).
+
+**Código**: `src/core/marketplace/` (`catalogo.ts`, `instalar.ts`, `doctor.ts`, `features.ts`, `index.ts` con el patrón de wiring documentado).
+
+**Test**: `test/marketplace.test.ts`.
+
+## Registro declarativo de proveedores — describir cada proveedor LLM como datos públicos de catálogo
+
+Resuelve el problema de añadir un proveedor LLM sin tocar código disperso: toda su descripción (familia de API, baseUrl por defecto, modelos con contexto y costes, mecanismo de auth, features) es UNA entrada declarativa en una tabla tipada.
+
+**Activa**: automático a nivel de tipos — la tabla `PROVIDERS` usa `satisfies Record<string, ProviderDefinition>`, así que cualquier proveedor nuevo incompleto o familia de API nueva sin soporte rompe la compilación. Se consulta por API (`resolverProveedor`, `listarProveedores`, `buscarPorModelo`) y sirve de puente para el discovery de runtimes (`resolverPorBaseUrl`).
+
+**Garantiza**:
+- Completitud compile-time: campos requeridos y uniones cerradas (`familia`, `tipo`) verificadas por el compilador, no por tests.
+- Resolución case-insensitive de ids con definición canónica devuelta; error útil (`ProveedorDesconocidoError`) que lista los conocidos y cómo añadir uno nuevo.
+- Búsqueda de modelos exacta, única y múltiple (p. ej. openrouter replicando catálogos ajenos).
+- Puente discovery→registry: endpoints descubiertos heredan familia/features de la tabla cuando su baseUrl casa (normalizando barra final y caso).
+
+**No garantiza**:
+- NUNCA contiene claves ni secretos: el auth es una referencia a variable de entorno, OAuth o none — jamás el valor.
+- Un endpoint local cuya baseUrl nadie declara NO es error: `resolverPorBaseUrl` devuelve undefined (es legítimo).
+- La comparación de modelos es exacta: alias o variantes de id no casan.
+
+**Código**: `src/core/proveedores-registry/` (`tipos.ts`, `definiciones.ts`, `resolver.ts`, `index.ts`).
+
+**Test**: `test/proveedores-registry.test.ts`.
+
+## Grafo episódico de memoria — recall que encuentra memorias conectadas aunque no compartan léxico
+
+Resuelve el techo del recall plano (ME1): este solo recupera memorias que comparten palabras con la consulta. El grafo añade un salto de expansión por afinidad entre memorias, recuperando las conectadas a los aciertos aunque no compartan ninguna palabra con ella.
+
+**Activa**: llamada a `recallConGrafo(almacen, consulta, k)` sobre el almacén híbrido de memoria; reúsa `recordar()` del almacén como semillas. Automático dentro del pipeline de recall del motor de memoria.
+
+**Garantiza**:
+- Aristas medidas con tres señales baratas y locales, sin NLP pesado: Jaccard de tokens (peso 0.5), entidades compartidas extraídas con regex simples (@menciones, rutas de fichero, nombres propios capitalizados; peso 0.3) y proximidad temporal con decaimiento exponencial (escala de una semana; peso 0.2).
+- Re-ranking determinista según el contrato ME5: `puntuacion × 0.7 + pesoAristaHaciaSeed × 0.3`.
+- Aristas bajo el umbral (0.05) no se crean: sin señal no hay arista.
+- Vecinos consultables top-k (`vecinosDe`), adyacencia ordenada por peso.
+
+**No garantiza**:
+- Construcción O(n²) en pares: pensado para n pequeño; no escala a corpus grandes sin particionar.
+- Solo UN salto de expansión desde las mejores semillas (~k/2): no hay búsqueda multi-salto ni recorrido completo del grafo.
+- La extracción de entidades es regex simple, no NLP: entidades mal capitalizadas o implícitas no generan señal.
+
+**Código**: `src/core/memoria/grafo.ts`.
+
+**Test**: `test/memoria-grafo.test.ts`.
+
+## Commit agéntico — mensajes generados conversando con herramientas sobre el diff real, con split por tema y CHANGELOG
+
+Resuelve el problema del mensaje de commit inventado: en lugar de una pasada ciega map-reduce, el modelo decide qué mirar (diff de un fichero concreto), ve el estilo real del repo y propone; la propuesta se valida contra el diff antes de aceptarse. Con `--split`, además separa el índice en commits coherentes por paquete/tema y alimenta los changelogs correspondientes.
+
+**Activa**: comando `ada-cli commit [--split] [--hacer] [--model <p/m>] [--detalle]`. Sin `--hacer` solo imprime la propuesta por stdout (canalizable: `ada-cli commit | git commit -F -`).
+
+**Garantiza**:
+- Lee SIEMPRE el índice (`git diff --cached`), nunca el árbol de trabajo: el mensaje describe exactamente lo que se va a commitear.
+- Validación estructurada contra el diff: todo fichero citado que no esté en el índice es un ERROR que se devuelve al modelo como recordatorio sintético (hasta 3×); titulares genéricos («varios cambios», «wip») detectados y rechazados.
+- Degradación honesta: si no hay propuesta válida tras los recordatorios, mensaje DETERMINISTA generado desde los datos reales del diff, marcado `usedFallback` — sabrás que salió sin el modelo, no con él.
+- `--split`: agrupado determinista y LOCAL (sin modelo) por paquete del monorepo o primer segmento; lockfiles huérfanos se asignan al grupo de su manifiesto más cercano (nunca un commit «chore» que no explica nada). Cada commit sale con su mensaje validado con las mismas garantías agénticas.
+- CHANGELOG Keep-a-Changelog por paquete: entradas nuevas bajo `## [Unreleased]` en su sección según tipo convencional, dedupe case-insensitive (regenerar no duplica líneas), destino = CHANGELOG.md más cercano subiendo desde los ficheros del grupo; si no existe ninguno se crea en el directorio común — las entradas no se tiran al changelog del vecino ni se callan.
+- En fallo (índice vacío o modelo caído): código de salida 1 y stdout VACÍO, para que nada falso se cuele encadenado a `git commit -F -`.
+
+**No garantiza**:
+- Nunca commitea por su cuenta sin `--hacer`.
+- Máximo 3 rondas de recordatorio; después cae al fallback determinista.
+- El agrupador por tema entiende monorepos `packages/<x>/` y primeros segmentos: esquemas de layout distintos no se agrupan tan fino.
+
+**Código**: `src/core/commits/` (`agentic.ts`, `split.ts`, `changelog.ts`, `diff.ts`, `git.ts`) + `src/cli/commit-command.ts`.
+
+**Test**: `test/commit-agentic.test.ts`, `test/changelog.test.ts`.
+
+## Discovery de runtimes locales/proxies — encontrar los modelos servidos en tu máquina o proxy sin configurar nada
+
+Resuelve el problema de descubrir qué modelos hay disponibles en runtimes locales y proxies compatibles (Ollama, LM Studio, LiteLLM, new-api/one-api, listas estilo OpenAI) sondeando sus endpoints HTTP conocidos y construyendo un catálogo unificado.
+
+**Activa**: llamada a `descubrirRuntimes({ extraBases?, authHeaders?, signal? })`. Sondea automáticamente las bases loopback por defecto (Ollama en `http://127.0.0.1:11434`, LM Studio en `http://127.0.0.1:1234`); bases remotas adicionales vía `extraBases`.
+
+**Garantiza**:
+- Cobertura por familia: Ollama (`/api/tags` + `/api/show` para num_ctx/capabilities), LM Studio nativo y v0 (`/v1/models`, `/api/v0/models`, contexto desde campo del endpoint o preset INI local en `~/.lmstudio`/`~/.cache/lm-studio`), openai-models-list enriquecido (`/v1/models` + `/v1/models/:id`), LiteLLM rich→fallback (`/model/info` si existe, si no `/v1/models`) y proxies new-api/one-api con routing por `supported_endpoint_types`.
+- Timeouts diferenciados: loopback 250 ms, remoto 10 s — un runtime muerto no cuelga el descubrimiento.
+- Dedup por URL normalizada: el mismo endpoint no aparece dos veces.
+- Catálogo por modelo (`modelosDisponibles`) anotado con el id del proveedor declarativo cuya baseUrl casa (puente con `proveedores-registry`).
+- Fetch inyectable y AbortSignal para tests y cancelación externa.
+
+**No garantiza**:
+- llama.cpp NO se duplica aquí: esa familia ya vive en `extensions/llama/` y está excluida del agregador deliberadamente.
+- Un runtime lento (>250 ms loopback) puede no aparecer: el timeout de sondeo es corto a propósito.
+- El contexto de modelo (`contextLength`) es opcional: si el endpoint y el preset INI no lo dan, no se inventa.
+
+**Código**: `src/core/descubrimiento/runtimes/` (`index.ts` agregador, `ollama.ts`, `lm-studio.ts`, `litellm.ts`, `tipos.ts`).
+
+**Test**: `test/runtimes-discovery.test.ts`.
+
+## URIs internas — 8 esquemas `esquema://…` accesibles desde read/edit sin tocar upstream
+
+Resuelve el problema de dar al modelo acceso uniforme a recursos internos (memoria, vault, reglas, auditoría, parches, limpieza, LSP, share) con un espacio de nombres propio: cualquier texto con `://` entra en ese espacio y nunca se interpreta como ruta de fichero.
+
+**Activa**: automático — las tools `read` y `edit` se envuelven con el router (`envolverReadConRouter`/`envolverEditConRouter`) y se reemplazan por inserción en el Map de tools de la sesión; el modelo ve la misma tool con la descripción ampliada con los esquemas disponibles. Extensible por registro: `registrar(esquema, handler)` añade o reemplaza handlers sin tocar el fichero del router.
+
+**Garantiza**:
+- Los 8 esquemas registrados por defecto: `memory://`, `vault://`, `rule://`, `audit://` (con dispatch real a memoria, bóveda, reglas y libro de auditoría) y `patch://`, `cleanse://`, `lsp://`, `share://` (fachada con validación y dispatch).
+- Parsing con frontera literal: `null` cuando el texto no tiene forma de URI (no aplica), error útil con la lista de esquemas disponibles cuando el esquema no está registrado.
+- Validación por esquema: `lsp://` exige consulta, `share://` exige id alfanumérico con guiones, ningún resto acepta caracteres de control.
+- Cutover limpio: el código nuevo vive en módulos Ada-owned; cero hunks en ficheros de upstream.
+
+**No garantiza**:
+- Los handlers de los 4 esquemas nuevos (`patch`, `cleanse`, `lsp`, `share`) son contratos de fachada del router (placeholder validado y despachado), no la implementación completa de cada slice: `patch://` no toca `core/parche/` (propiedad de D03).
+- `core/router-uris/` es un shim de re-export de `core/rutas/`: no hay dos routers, solo uno.
+
+**Código**: `src/core/rutas/` (`router.ts`, `envoltorio.ts`, `index.ts`); `src/core/router-uris/` (re-export); cableado en `src/core/urls-internas/lector.ts`.
+
+**Test**: `test/router-uris.test.ts`.
+
+## Cleanse — arregla en paralelo los diagnósticos que YA reportan los comprobadores de tu proyecto
+
+Resuelve el problema de pasar de «hay 40 problemas de lint/typecheck/test» a «están arreglados», lanzando un subagente por fichero con verificación real, sin inventarse comprobadores ni aceptar arreglos que no se demuestran.
+
+**Activa**: comando `ada-cli cleanse [--dry-run] [--fix] [--concurrency N] [--model <provider/model>]`. La detección es automática mirando lo que hay: scripts de package.json, tsconfig, biome/eslint, ruff, cargo clippy, go vet, gradle/maven (wrapper incluido).
+
+**Garantiza**:
+- Cero comprobadores inventados: `detectarComprobadores` documenta en `mirado` cada sitio comprobado aunque no encuentre nada — distingue «no he mirado» de «he mirado y no hay nada».
+- Streaming exactly-once (C06): cada diagnóstico se emite UNA sola vez aunque el checker reimprima la línea en varios flushes; el corte es en la última `\
+` con intervalo de 5 s para checkers parcialmente silenciosos.
+- Balanceo por peso (error=5, +2 sin línea, +1 sin regla, +1 sin sugerencia): los ficheros más rotos y menos accionables se reparan primero.
+- Ownership sticky por fichero: todos los diagnósticos tardíos de un fichero van al mismo worker; si llega tarde y el dueño vive, steering por IRC; si murió o el canal falla, reencola.
+- Verificación honesta del arreglo: tras cada arreglo se RE-EJECUTAN todos los comprobadores de alcance «fichero» (un arreglo de lint que rompe el typecheck del mismo fichero no pasa por limpio). Un arreglo se acepta solo si el diagnóstico original desapareció Y no apareció ninguno nuevo en ese fichero, comparando por firma (comprobador+regla+mensaje, inmune al desplazamiento de líneas). Si no se acepta, el fichero SE REVIERTE al contenido previo — rechazar de verdad, no solo decirlo.
+- Tablero vivo: TTY repinta filas por checker/grupo sin scroll; no-TTY/CI emite líneas `[start]/[done]/[fail]` estables.
+
+**No garantiza**:
+- Los comprobadores mutadores (clippy --fix, etc.) solo corren con `--fix`.
+- Diagnósticos de proyecto entero (test runners, sin `ruta`) forman su propio grupo: no se atribuyen a fichero alguno.
+- No ejecuta comprobadores que el proyecto no tenga configurados.
+
+**Código**: `src/core/limpieza/` (`reparacion.ts` orquestador, `comprobadores.ts`, `flujo.ts`, `peso.ts`, `pool.ts`, `tablero.ts`, `parseo.ts`, `tipos.ts`) + `src/cli/cleanse-command.ts`.
+
+**Test**: `test/cleanse-comprobadores.test.ts`, `test/cleanse-reparacion.test.ts`, `test/cleanse-sticky.test.ts`.
+
+## Usage multi-cuenta — quién gastó cuánto, con identidades redactadas y series temporales legibles
+
+Resuelve la pregunta org-decisiva cuando hay varias credenciales en juego: `aggregate.ts` dice cuánto se gastó; esto dice QUIÉN lo gastó, con serie temporal por día y máscaras estables que permiten seguir una cuenta entre ejecuciones sin revelar su identidad.
+
+**Activa**: comando `ada-cli usage` (panel multi-cuenta con sparklines y máscaras). Agrega los mismos JSONL de sesión que el resumen global; la cuota viva (lo que QUEDA) se pregunta al proveedor con la credencial ya guardada, cacheada unos minutos, para anthropic, openrouter, openai-codex, github-copilot y google-gemini.
+
+**Garantiza**:
+- Identidad de cuenta: `accountId` explícito del JSONL si viene; si no, huella de la API key usada — SHA-256 truncado a 16 hex con prefijo de proveedor (`proveedor#huella`) — la clave NUNCA viaja entera, ni en memoria ni en salida, y dos claves iguales en proveedores distintos no se funden en una cuenta.
+- Redacción keyed: cada identidad se sustituye por una máscara `AMIGABLE-XXXX` derivada con HMAC-SHA256 usando la clave per-install de secretos (persistida, 0600, jamás enviada a proveedor) — misma entrada produce siempre la misma máscara, entradas distintas producen máscaras distintas (charset base32 sin I/L/O/0/1 para no confundirlas a ojo), y de la máscara no se vuelve a la identidad ni por diccionario.
+- Filtros espejo del resumen global (directorios temporales fuera, filtro `desde`, solo respuestas del asistente): el total multi-cuenta CUADRA con el total general — dos paneles que no suman lo mismo es cómo empieza a mentir un panel.
+- Sparklines de bloques a ancho fijo: normaliza min→▁ max→█; serie plana → todo ▁ (nunca inventa pendiente); series largas reducidas por medias de cubo.
+- Cuota viva cacheada para no sumar una petición HTTP a cada turno; en la clave de caché solo los últimos caracteres del secreto.
+
+**No garantiza**:
+- No estima nada: suma lo que el proveedor cobró (`usage` de cada mensaje del asistente); donde no hay dato, no hay número.
+- Los tokens de caché van APARTE del total (mezclarlos enseñaría un gasto que no se corresponde con la factura: en DeepSeek un acierto cuesta ~1/31 de un fallo).
+- Si la clave de secretos no existe, NO se crea al redactar: cae a una clave derivada del agentDir (peor caso aceptado — instala normal usa siempre la de secretos).
+- Consultor de cuota solo para los 5 proveedores registrados; `ultimoUso` falta si ninguna línea del JSONL traía timestamp.
+
+**Código**: `src/core/usage/` (`aggregate.ts` global, `multi.ts` multi-cuenta + sparklines, `redaccion.ts` máscaras, `cuota/` consultores por proveedor) + `src/cli/usage-command.ts`.
+
+**Test**: `test/usage-aggregate.test.ts`, `test/usage-multi.test.ts`, `test/usage-cuota.test.ts`.