@hoilab/ada-cli 0.84.21 → 0.85.0

package/CHANGELOG.md

@@ -1,10 +1,55 @@
 # Changelog
 
-## [Unreleased]
+## [0.85.0] - 2026-08-25
 
-### Fixed
+### Added
+
+- **Added PDF reading without a browser.** `read` on a PDF now extracts its **text layer** using only `node:zlib` — content streams travel Flate-compressed, so no new dependency and no headless browser are needed (the competing agent renders the document and screenshots it; that buys exact layout at the cost of a browser per read). Three states are told apart, never two: text extracted (truncated with the same limits as any other file); **scanned / image-only** — reported as such, instead of passing for an empty file; and **cannot read** (encrypted or malformed), with the reason. The `%PDF-` signature is checked against the file's first kilobyte, never against its extension.
+- **Added detection of empty model turns.** A provider answering a well-formed request with *nothing* — no text, no reasoning, no tool calls (`x-preview-f-free` did exactly that) used to look like success everywhere: `ada-cli -p` printed an empty stdout and exited 0, and the task bench counted the case as "the model chose not to edit". Both halves are fixed: print mode now writes `El modelo no ha contestado: …` to stderr and exits 1; the interactive session emits a warning notification; and the bench reports those cases separately (`vacío`) instead of counting them as ghosts. An unknown content block or a reasoning-only turn never triggers the notice — the detector stays silent about anything that might be something.
+
+- Added OTLP export of the session ledger to your own OpenTelemetry collector (`ada-cli telemetria`, `--cuerpo`, `--enviar`), following the standard `OTEL_EXPORTER_OTLP_*` contract. What leaves the machine comes from an **explicit allowlist of shape** — event type, tool, exit code, byte counts, hashes, destination domain, provider, model, token counts — and the number of attributes dropped is recorded so a silent truncation cannot pass for a complete export. A second belt discards any value containing a newline or longer than 200 characters even if its key is allowed. There is deliberately no environment variable, option or parameter that enables content export, and a test walks the module's own source to keep it that way; `--cuerpo` prints the exact JSON that would be sent so you can verify it rather than take our word for it.
+- Added a software bill of materials and a licence gate: `npm run sbom` writes CycloneDX 1.5 (reproducible byte for byte), and `npm run check:licencias` fails on a denied **or unknown** licence. A dependency that declares no licence is *unknown*, and unknown does not pass; an empty dependency tree also fails, because a gate that passes because it inspected nothing is worse than no gate. Compound SPDX expressions (`OR`, `AND`, parentheses) are understood, and anything unparseable lands in *unknown*, never in *allowed*.
+- Added detection and masking of GDPR art. 9 special categories and art. 10 convictions before anything reaches disk, on both the audit ledger and the edit diary. National identifiers are validated rather than pattern-matched (Spanish DNI mod-23, IBAN mod-97), and vocabulary categories require a nearby person marker so that "diagnostic" in compiler output and "union" in SQL do not trigger. Measured over 469 real source files of this repository the detector produces 3 findings, down from 116 in the first implementation. Text that cannot be analysed is masked whole rather than passed through.
+- Added `ada-cli audit purge --dias N --politica "..."` (also `--antes-de AAAA-MM-DD`, with `--dry-run`), which writes a chained tombstone into the session ledger before deleting anything. A lawful retention purge under GDPR art. 5.1.e used to either trip the tamper alarm (deleting `sesion/`) or vanish without trace while the ledger still reported "intact" (deleting both directories). `audit verify` now reports purges as *explained* gaps, naming the policy they were carried out under, and reports them even when no gap remains — which is the normal case, since a purge removes the file and its index anchor.
+- Added a machine-wide policy scope that the user cannot edit, at `/Library/Application Support/Ada/politica.json`, `/etc/ada/politica.json` and `%ProgramData%\Ada\politica.json`. It can only ever *restrict*: a `modoMaximo` ceiling lowers the requested permission mode and never raises it, and `denegadas` disables tools for the whole fleet in a way `yolo` cannot lift. Until now both configuration scopes were files the user owned, so the line a CISO added to forbid `yolo` could be deleted by the very person it applied to. Inspect it with `ada-cli politica`.
+- Added transcript usage notices for compaction and branch summaries when cache miss notices are enabled.
+
+### Changed
 
+- **Removed the install ping to `pi.dev`.** `reportInstallTelemetry` sent the version and user agent of every installation to `https://pi.dev/api/report-install`, enabled by default. It is gone, and is not replaced by an endpoint of our own.
+- **Removed the default provider attribution headers** (`HTTP-Referer: https://ada.dev` and `X-OpenRouter-Title` on OpenRouter, `X-BILLING-INVOKE-ORIGIN` on NVIDIA NIM, `User-Agent: ada-cli` on Cloudflare). None of them were needed for a request to work; they told the provider which tool the client uses. Attribution is still possible for anyone who wants it, by configuring the headers on the model. The functional `x-opencode-session` header is unaffected. As a result `enableInstallTelemetry` no longer governs anything and is documented as inert.
+- Changed session sharing to render clickable terminal links and Radius shares to display only the artifact's canonical URL.
+
+### Fixed
+
+- **Fixed aborting a turn leaving the whole conversation unresumable.** When a message arrived with stop reason `aborted` or `error`, the agent loop returned without closing the tool calls that same message already carried. A `tool_use` without its `tool_result` is rejected by providers, so pressing Ctrl-C at the wrong moment did not leave the turn half-done — it left the conversation unable to resume. The test that was meant to guard this had a mock that reported `aborted` while returning a message whose stop reason said `toolUse`, which sent the loop into an infinite retry at 99% CPU: it did not fail, it hung, and with it the whole suite for 71 measured minutes. That is why the defect went unseen.
+- **Fixed `ada-cli session <id> <op>` failing with an opaque error on installed copies.** The protocol extension point it needs is added by this fork to upstream's client/protocol/server packages, which the published package resolves from the registry — so an installed copy does not carry it. It now explains that and points at a source build, instead of crashing with `client.extension is not a function`.
+- **Fixed the published package being uninstallable, and then broken at runtime.** Both found by packing the tarball and installing it the way a user would, before publishing. First, `npm version --workspaces` had rewritten the dependency *ranges* too, so the package asked for `@earendil-works/pi-agent-core@^0.85.0` — a version upstream never published — and every `npm install` failed with `notarget`. Then, with that fixed, the installed copy died with `Cannot find package 'typescript'`: six files under `src/core/` import TypeScript at module load and it was only a devDependency, so structural editing and post-edit type checking were broken for every client. Two gates now catch both classes: `check-dependencias-resuelven.mjs` (every declared range has a published version that satisfies it) and `check-imports-de-runtime.mjs` (no production file imports a dev-only dependency).
+- **Fixed the argument coercion not being applied on the path the SDK actually uses.** It was wired into `createTool`/`createToolDefinition`, which looked like the funnels but are not: `createCodingTools` calls each factory directly and bypassed them. The tests passed while the installed copy still rejected the call. It now lives in `wrapToolDefinition`, which every tool does go through — verified by installing the tarball and running it against a real free model: **4 model calls and no validation rejections, matching the competing agent**.
+- **Fixed our own fixes not reaching anyone who installs from npm.** `@hoilab/ada-cli` declares `"@earendil-works/pi-ai": "^0.84.2"` and the shrinkwrap resolves it from the registry, so an installing user gets **upstream's** tarball, not our patched copy. Measured on the real artifact with `npm pack --dry-run`: 2,066 files, **zero** from `pi-ai`. Fourteen of our patches live in packages we do not publish, including the two most important ones of this release. The tolerant JSON parse now also lives in the package that *is* published and is used by `edit`'s argument preparation, verified by unpacking the tarball and running it outside the repository. A gate (`check-fork-llega-al-usuario.mjs`, wired into `prepublishOnly`) now blocks publishing while any patch sits in an unpublished package, so this cannot pass unnoticed again.
+- **Fixed a tool argument arriving as a JSON string with raw tabs costing a whole turn.** The root cause was not that the argument was a string — `edit` had handled that since before — but that the string contained **raw control characters**. Measured on a real payload: 309 characters with 18 raw tab characters inside JSON string literals, which JSON forbids, so `JSON.parse` answered *Invalid control character* and a silent `catch {}` swallowed it. That is what every model produces when it writes tab-indented code inside an argument. Argument coercion now parses tolerantly — escaping raw control characters only inside string literals, leaving valid JSON byte-identical and still rejecting genuinely malformed JSON — and it runs before TypeBox's `Value.Convert`, which otherwise wraps the string in a one-element array and destroys the evidence. Measured against `nvidia/nemotron-3-ultra-550b-a55b:free` on the same task as a competing agent: **6 model calls and one validation rejection before, 4 calls and none after — the same round-trip count as the competitor**, with equivalent output.
+- **Fixed a tool argument arriving as a JSON string costing a whole turn.** Small models routinely send nested JSON as a string, and the argument coercion covered number, integer, boolean, string and null but not array or object. Measured against `nvidia/nemotron-3-ultra-550b-a55b:free` on the same task as a competing agent: 6 model calls and 42,717 input tokens versus their 4 and 29,393, with identical final code. Two of those six round trips were a stringified `edits` array, its rejection, and the recovery. Coercion is applied only when the schema asks for an array or object and the text parses to exactly that type, so a bash command beginning with `[` remains a string and a malformed JSON still produces the validation error that tells the model what shape was expected.
+- **Fixed tool calls rejected before execution leaving no trace in the audit ledger.** Argument validation runs before the audit hook, so a call that failed validation — or named a tool that does not exist — reached neither of the recording points. A real run had two `edit` calls in the transcript and one in the ledger. They are now reconciled on the next model message and recorded as `no-ejecutada`.
+- **Fixed the machine-wide update check being able to install a package outside our own scope.** A remote-announced package name is now accepted only within our npm scope, so a legitimate rename is still followed while a jump to someone else's scope is refused out loud.
+- **Fixed `ada-cli update` being one upstream release away from installing a different product.** The version check queried `https://pi.dev/api/latest-version`, which answers `{"version":"0.84.3","packageName":"@earendil-works/pi-coding-agent"}`, and the self-update plan built its `npm install -g` spec from *that* package name. It did not fire only because 0.84.3 is not greater than our 0.84.22 — arithmetic, not design. The check now queries the npm registry for our own package, and the install spec always uses our own package name regardless of what any server replies.
+- **Fixed `audit verify` accusing an intact installation of tampering.** A single condition answered two different questions and always blamed the first, so a file written by two desktop processes — each starting its own chain — was reported as "the hash of an entry does not match its content" when it matched perfectly, and verification stopped there. Three causes are now told apart: an edited entry, a broken link, and a chain restart. A restart is neither an accusation nor an absolution: it is reported with its file and timestamp, and counting continues.
+- **Fixed the DPO report hiding its own scope caveat whenever there was data.** The sentence naming which network paths the ledger observes travelled inside the "nothing happened" text, which is only printed when the table is empty. The caveat matters more with rows than without: an empty table asserts an absence, a populated one implies an exhaustive list. It is now always rendered, and the list of uncovered paths — which was wrong — was rebuilt by walking every `fetch(` in the source and is now guarded by a test.
+- Fixed writes to `auth.json` and `models-store.json` overriding administrator-managed file permissions and ACLs ([#7779](https://github.com/earendil-works/pi/issues/7779)).
+- Fixed UTF-8 BOM markers preventing frontmatter and user configuration files from loading ([#8337](https://github.com/earendil-works/pi/issues/8337)).
+- Fixed invalid settings files being easy to miss during interactive startup by rendering warnings with the file path inside the TUI ([#7829](https://github.com/earendil-works/pi/issues/7829)).
+- Fixed the subagent example repeatedly prompting before running project-local agents in trusted repositories ([#8261](https://github.com/earendil-works/pi/issues/8261)).
+- Added `session_compact_failed` extension events so compaction failures and aborts expose their reason, retry state, source, and error message to handlers ([#8175](https://github.com/earendil-works/pi/issues/8175)).
+- Fixed npm package update checks treating older registry versions as available updates, preventing `pi update` from downgrading already-newer installed packages ([#8226](https://github.com/earendil-works/pi/issues/8226)).
+- Fixed built-in llama.cpp models disappearing from `/model` when `/llama` refreshed a configured server under `PI_OFFLINE`, and included idle-slept `sleeping` router models in the selectable catalog ([#8167](https://github.com/earendil-works/pi/issues/8167)).
+- Fixed `pi.registerFlag()` accepting default values that do not match the declared flag type ([#8064](https://github.com/earendil-works/pi/issues/8064)).
 - Fixed Z.AI Coding Plan defaults referencing the removed GLM-5.1 model ([#8096](https://github.com/earendil-works/pi/issues/8096)).
+- Fixed repeated ambiguous truncated-response recovery being mislabeled as context overflow ([#8130](https://github.com/earendil-works/pi/issues/8130)).
+- Fixed duplicate fullscreen right-click paste in VS Code-based terminals on Windows ([#8186](https://github.com/earendil-works/pi/issues/8186)).
+- Fixed llama.cpp login guidance to direct users to `/llama` before `/model` when no local models are loaded ([#8203](https://github.com/earendil-works/pi/issues/8203)).
+- Fixed hung pi.dev model catalog requests consuming the entire refresh deadline without retrying ([#8198](https://github.com/earendil-works/pi/issues/8198)).
+- Fixed inherited Xiaomi model catalogs listing shut-down MiMo V2 models in `/model` and `--list-models` ([#8187](https://github.com/earendil-works/pi/issues/8187)).
+- Fixed branch summary entries recording the navigation destination in `fromId` instead of the pre-navigation source leaf.
+- Fixed threshold auto-compaction being skipped when providers omit streaming usage data ([#8328](https://github.com/earendil-works/pi/issues/8328)).
 
 ## [0.84.2] - 2026-08-14
 
@@ -36,6 +81,8 @@
 
 ### Fixed
 
+- Fixed root Markdown files such as `README.md` and `AGENTS.md` in skill directories being reported as broken skills unless they declare valid skill frontmatter ([#7805](https://github.com/earendil-works/pi/issues/7805)).
+- Fixed single-object `edit` tool inputs failing validation by accepting them as one-edit arrays in both coding-agent and harness edit tools ([#7835](https://github.com/earendil-works/pi/issues/7835)).
 - Fixed managed-tool downloads delaying TUI startup and hiding diagnostics in fullscreen mode by mounting the TUI first and showing download progress and warnings inside it.
 - Fixed opening a model selector immediately after startup cancelling and restarting the in-progress model catalog refresh.
 - Fixed inherited GitHub Copilot login triggering API rate limits while enabling model policies by limiting concurrent policy updates ([#6187](https://github.com/earendil-works/pi/issues/6187)).

package/README.es.md

@@ -0,0 +1,174 @@
+<p align="center">
+<pre>
+  █████╗ ██████╗  █████╗
+ ██╔══██╗██╔══██╗██╔══██╗
+ ███████║██║  ██║███████║
+ ██╔══██║██║  ██║██╔══██║
+ ██║  ██║██████╔╝██║  ██║
+ ╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝
+</pre>
+</p>
+
+<h3 align="center">Ada CLI — el agente de código autónomo de nivel enterprise</h3>
+
+<p align="center">
+  <a href="https://discord.com/invite/3cU7Bz4UPx"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
+  <a href="https://www.npmjs.com/package/@hoilab/ada-cli"><img alt="npm" src="https://img.shields.io/npm/v/@hoilab/ada-cli?style=flat-square" /></a>
+</p>
+
+<p align="center"><a href="README.md">🇬🇧 English</a> · 🇪🇸 Español</p>
+
+> Ada CLI es el fork de HOILAB de [pi.dev](https://pi.dev) (`earendil-works/pi`): el binario `pi` pasa a ser `ada-cli`, la configuración se mueve a `~/.ada/`, y el fork se sincroniza automáticamente con upstream cada día para que los parches de seguridad y los modelos nuevos lleguen sin demora. Ver [ADA-CLI.md](../../ADA-CLI.md) para la mecánica completa de sincronización. Los issues y PRs de contribuidores nuevos se cierran automáticamente por defecto — ver [CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+---
+
+Ada CLI es un agente de código construido sobre el núcleo mínimo y probado de pi.dev, con un **Ada Intelligence Engine** añadido encima: persecución autónoma de objetivos con un juez obligatorio que exige evidencia, workflows paralelos en sandbox, un grafo de trazabilidad que bloquea el "hecho" sin evidencia observada, memoria durable entre sesiones con log de auditoría a prueba de manipulación y escaneo de PII, secretos cifrados, y una app de escritorio nativa — todo conectado al mismo `settings.json` que ya usa tu terminal.
+
+Donde la mayoría de agentes de código te piden confiar en un chat largo sin más, Ada está construido para ser **auditable**: cada acción autónoma tiene evidencia citada detrás, o no ocurre.
+
+- **Todo es opcional e inspeccionable.** El núcleo se mantiene tan mínimo como el de pi.dev — cuatro tools (`read`, `write`, `edit`, `bash`) por defecto. Autonomía, memoria y orquestación son capas opcionales que puedes desactivar en `settings.json`.
+- **La autonomía exige un contrato aprobado.** El [Goal Engine](#ada-intelligence-engine) no toca el código hasta que apruebas su plan con `/goal approve`, ejecuta fases TDD fijas, y nunca marca un trabajo como `done` sin que un juez cite la evidencia.
+- **Nada está "hecho" solo porque el modelo lo diga.** El [Work Graph](#ada-intelligence-engine) bloquea dar algo por completado sin evidencia observada — un test que pasa, un diff real, un comando verificado — nunca una afirmación en el transcript.
+- **La memoria es compliance-ready por defecto.** El [Memory Engine](#ada-intelligence-engine) bloquea datos PII antes de escribirlos en disco y mantiene un log de auditoría encadenado (hash-chain) de cada escritura y rechazo.
+- **Los secretos nunca tocan el contexto del modelo.** El [Vault](#ada-intelligence-engine) integrado es un almacén local cifrado, compartido entre el CLI, la app de escritorio y los subagentes de una sesión desbloqueada.
+- **Los equipos tienen una GUI, no solo terminal.** La app [Ada Desktop](../../desktop/) (Tauri + Next.js) usa exactamente el mismo SDK y la misma configuración que el CLI — sin producto paralelo que mantener.
+- **Extensible en vez de opinada.** Sin MCP integrado por defecto, sin framework de sub-agentes forzado, sin popups de permisos — construye exactamente el flujo que necesitas con [extensiones](docs/extensions.md), [skills](docs/skills.md), o [paquetes de Ada](docs/packages.md) de terceros. Ver [Filosofía](#filosofía).
+
+## Primeros pasos
+
+```bash
+npm install -g --ignore-scripts @hoilab/ada-cli
+```
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+ada-cli
+```
+
+O autentica con una suscripción existente: ejecuta `ada-cli` y luego `/login`. La primera vez que arrancas en un proyecto nuevo, Ada pide confiar en la carpeta — ver [Project Trust](docs/security.md).
+
+Guía completa: [Quickstart](docs/quickstart.md) · [Proveedores y modelos](docs/providers.md) · [Windows](docs/windows.md) · [Termux](docs/termux.md) · [tmux](docs/tmux.md)
+
+## Pensado para enterprise
+
+- **Autonomía gobernada.** Los modos de permiso (`ask` / `auto` / `plan` / `full`) y los frenos `askBefore` del Goal Engine bloquean acciones irreversibles (publicar, borrar, gastar) tras aprobación explícita, tanto en el CLI como en la app de escritorio.
+- **Evidencia por encima de afirmaciones.** Tanto el juez del Goal Engine como los gates del Work Graph exigen evidencia citada y observada antes de contar algo como completo — ningún run autónomo puede marcarse "hecho" en silencio.
+- **Privacidad y auditoría integradas.** `memoryPrivacyLevel: "strict"` (por defecto) bloquea PII antes de persistirla; cada escritura, rechazo y búsqueda de memoria queda encadenada (hash-chain) en un log de auditoría vía `/memory-audit` — pensado para sostener obligaciones de RGPD/AI Act sin herramientas adicionales.
+- **Aislamiento de secretos.** Las credenciales del Vault nunca entran en el contexto de prompt del modelo ni tocan disco sin cifrar.
+- **Runs presupuestados y acotados.** Toda superficie autónoma (Goal Engine, Workflows) impone límites de turnos, detección de bucles repetidos, un stop-file como interruptor de emergencia, y presupuestos de tokens/coste — sin gasto abierto.
+- **Desplegable como CLI o escritorio.** Mismo SDK, mismo `settings.json`, mismo rastro de auditoría, trabaje tu equipo en terminal o en una GUI.
+- **Siempre al día automáticamente.** Una sincronización diaria determinista (`scripts/sync-ada.sh` + GitHub Action) rebasa sobre pi.dev upstream, así que los parches de seguridad y el soporte de nuevos proveedores llegan sin seguimiento manual de parches.
+
+## Ada Intelligence Engine
+
+pi.dev es deliberadamente mínimo — su propia filosofía es saltarse sub-agentes y modo plan, dejando que cada equipo lo extienda a su manera. Ada CLI apuesta lo contrario: envía esa capa de orquestación como parte del producto.
+
+| Módulo | Para qué sirve |
+|---|---|
+| 🎯 **Goal Engine** (`/goal`) | Persigue un objetivo de forma autónoma, turno a turno, a través de fases TDD fijas, bloqueado por un contrato (`doneCriteria` + `verifyCommand`) que hay que aprobar antes de empezar. Un juez obligatorio exige evidencia citada antes de marcar algo como hecho, respaldado por frenos de seguridad (límite de turnos, detección de bucles, stop-file, presupuesto de coste/tokens). |
+| ⚙️ **Workflows** (`/workflow`) | Orquesta varios agentes en paralelo mediante scripts JS en sandbox, presupuestados y resumibles tras una interrupción. Trae 5 builtins listos para usar: investigación profunda, code review, construir producto, auditoría de código, multi-perspectiva. |
+| 🕸️ **Work Graph** (`/graph`) | Un grafo tipado que conecta intención → requisito → tarea → archivo → test. Los gates bloquean declarar un trabajo "hecho" sin evidencia observada — nunca solo con la palabra del modelo. |
+| 🧠 **Memory Engine** (`/memory-audit`, `/memory-consolidate`, `/memory-insights`) | Memoria durable en 3 capas (global, proyecto, fallos pasados) con búsqueda de texto completo sobre sesiones anteriores, un log de auditoría a prueba de manipulación, y un escáner de PII que bloquea datos sensibles antes de guardarlos. |
+| ✨ **Prompt Optimizer** | Antes de procesar una petición, decide si hace falta preguntar hasta 3 huecos críticos (`clarify`) o reescribirla como prompt estructurado (`enhance`). |
+| 🔐 **Vault** (`/vault`) | Almacén local de secretos cifrado con passphrase, compartido entre el CLI, la app de escritorio y los subagentes de una sesión desbloqueada. |
+| 🖥️ **App de escritorio** | Tauri 2 + Next.js, sobre el mismo SDK y `settings.json` que el CLI. pi.dev es solo terminal. |
+| ⏰ **Scheduler** (`ada-cli schedule`) | Trabajo recurrente que corre dentro de `ada-cli serve`. `maxRuns` y `expiresAt` son **obligatorios**: un trabajo recurrente sin techo es gasto indefinido, y nadie se acuerda de apagarlo. Cada job usa su propia sesión para que dos programaciones no se contaminen el contexto. |
+| 🔁 **Continual Harness** (`ada-cli refine`) | Convierte lo aprendido en una sesión terminada en notas durables que se inyectan en prompts futuros. Cada propuesta **exige evidencia citada** (`fichero:línea`, un comando y su salida, un mensaje tuyo); las que no la traen se rechazan y te lo dice. El prompt de sistema base no se toca nunca. |
+| 🌐 **Tools web** (`web_search`, `web_fetch`) | TypeScript nativo, clave desde el vault cifrado y guardas SSRF: los rangos privados y el endpoint de metadatos del cloud se bloquean antes de hacer la petición. Opt-in por subagente: el acceso a red nunca se hereda de `readOnly`. |
+| 🔌 **MCP** (`mcp_list_tools`, `mcp_call_tool`) | Cliente MCP de TypeScript real, con los tokens en el vault. Exactamente **dos** tools, nunca una por herramienta remota: un servidor con 40 inundaría el system prompt y desplazaría el prefijo cacheable. |
+| 💾 **Optimizador de caché de prompt** | Reordena el system prompt para que lo estable vaya delante, mide el hit rate real por proveedor y repara las rarezas de cada uno. Con caché por prefijo el coste de un cambio depende de su **posición**, no de su tamaño — en DeepSeek un fallo cuesta 31 veces un acierto. |
+| 🖧 **Sesiones residentes** (`ada-cli serve` / `attach` / `session`) | El trabajo sobrevive al cierre del terminal. Puedes reengancharte para mirar o dirigir, y hacer `compact`, `rename`, `fork` o `kill` por el socket. |
+| 🧩 **Integración con editores** (`ada-cli acp`) | Habla Agent Client Protocol por stdio, así que Zed y cualquier cliente ACP pueden conducir Ada en vez del TUI. |
+
+<details>
+<summary><b>Comparativa fila a fila vs. pi.dev upstream</b> (verificado contra ambos códigos fuente)</summary>
+
+| | pi.dev (upstream) | Ada CLI (este fork) |
+|---|---|---|
+| Producto | CLI (`pi`) | CLI (`ada-cli`) **+ app de escritorio** |
+| Autonomía multi-turno | No incluida — se salta sub-agentes y modo plan por diseño | **Goal Engine**: bucle contrato-primero, fases TDD fijas, juez obligatorio con evidencia citada, frenos de seguridad |
+| Paralelismo orquestado | No | **Workflows**: scripts JS en sandbox (`node:vm`) con `agent()/parallel()/pipeline()`, journal resumible, 5 builtins |
+| Trazabilidad del trabajo | No | **Work Graph**: grafo tipado con finalización bloqueada por evidencia |
+| Memoria entre sesiones | Solo dentro de la sesión activa / context files (`AGENTS.md`) | **Memory Engine**: 3 capas durables + búsqueda de texto completo entre sesiones + log de auditoría a prueba de manipulación + escáner de PII |
+| Optimización de prompts | No | **Prompt Optimizer**: `clarify` o `enhance` antes de procesar |
+| Secretos | No | **Vault**, cifrado, compartido CLI/desktop/subagentes |
+| Slash commands | El set base de pi.dev | + `/goal` `/workflow` `/graph` `/vault` `/memory-audit` `/memory-consolidate` `/memory-insights` |
+| Anti-recursión | N/A | Las tools `goal_*`/`workflow`/`graph_add_nodes`/memoria solo se registran en la sesión principal — los subagentes nunca se auto-orquestan |
+| Sincronización con upstream | — (es el upstream) | Reset diario determinista + reaplicación de delta, sin merges manuales |
+
+</details>
+
+<details>
+<summary><b>Ada CLI vs. Prime Agent</b> (otro fork de pi.dev, 17k+ ⭐)</summary>
+
+[PrimeIntellect-ai/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent) también está construido sobre `earendil-works/pi`, con un modelo de ejecución basado en un kernel Python persistente y un "Continual Harness" auto-mejorable. Desglose completo con fuentes: [docs/AUDIT.md §8](../../docs/AUDIT.md).
+
+| Capacidad | Ada CLI | Prime Agent | Ventaja |
+|---|---|---|---|
+| Sesiones en background que sobreviven al cierre de terminal | `ada serve` / `ada attach` / `ada session` | Basado en daemon, `attach`/`detach` | Empate |
+| Integración con editores (Agent Client Protocol) | `ada acp` | Modo `acp` | Empate |
+| Trabajo recurrente / scheduling | `ada-cli schedule`, con `maxRuns`/`expiresAt` obligatorios | `/heartbeat`, cron schedules | Empate |
+| Auto-mejora de instrucciones | `ada-cli refine`, cada propuesta exige evidencia citada | `/refine` con snapshots de rollback | Empate |
+| Mensajería agente-a-agente | Bloqueada a propósito (anti-recursión por diseño) | Incluida | Trade-off de diseño, no un gap |
+| Skills ejecutables / con Python | Solo markdown, por decisión | Paquetes Python + skill-creator | Prime Agent |
+| Integración MCP | Cliente TypeScript nativo, tokens desde el vault | El protocolo vive dentro del kernel de Python | **Ada CLI** |
+| Búsqueda web | `web_search`/`web_fetch`, clave en el vault, con guardas SSRF | Skill de Python, clave en `auth.json` en claro | **Ada CLI** |
+| Optimización de caché de prompt | Estabilización de prefijo + medición de hit rate por proveedor | No tiene | **Ada CLI** |
+| Grafo de trazabilidad del trabajo | Sí, con gates de evidencia | No tiene | **Ada CLI** |
+| App de escritorio nativa | Sí | Solo TUI | **Ada CLI** |
+| Vault de secretos cifrado dedicado | Sí | `auth.json` plano | **Ada CLI** |
+| Juez obligatorio con evidencia | Sí, por defecto | Gates configurables por el usuario, no forzados | **Ada CLI** |
+
+Ver [docs/AUDIT.md](../../docs/AUDIT.md) para la auditoría técnica completa, la mecánica exacta de fork/sync, y el desglose de paridad capacidad por capacidad — incluido lo que decidimos deliberadamente NO copiar, y por qué.
+
+</details>
+
+### Las tres garantías, y lo que NO son
+
+Están impuestas en código, no por política. Cada línea es comprobable: abre el fichero y léelo.
+
+| Garantía | Dónde se impone |
+|---|---|
+| **Un goal no puede completarse sin que un juez cite evidencia.** El juez es independiente, solo ve el objetivo, sus `doneCriteria`, el `verifyCommand` y la evidencia citada, y corre cross-model. Sin veredicto no hay completado. | `workflows/goal-engine/engine.ts` (`runJudge`), `resource-loader.ts` |
+| **Un subagente no puede orquestar ni escribir memoria durable — estructuralmente.** Las tools sencillamente no existen en su registro; no es una comprobación de permisos que se pueda relajar. Aserto en `test/anti-recursion-tools.test.ts`. | `agent-session.ts` (gates de `_isSubagentSession`) |
+| **La memoria se escribe a través de un escáner de PII y un log de auditoría encadenado.** Los rechazos también quedan registrados, y `/memory-audit` verifica la cadena. | `memory-engine/scanner.ts`, `memory-engine/audit.ts` |
+
+**Lo que Ada NO afirma.** El sandbox `node:vm` contiene el *script orquestador*: no tiene `require`, `process` ni `import`, y no puede tocar el host. Pero los **agentes hoja que lanza son sesiones normales** con `read`/`bash`/`edit`/`write` y los mismos permisos de SO que cualquier agente de código, incluido el tuyo. Ada no es un sandbox de sistema operativo y no pretende serlo; para trabajo no confiable, ejecútalo en un contenedor. Lo que sí está contenido es la capa de orquestación, y las credenciales viven en un vault cifrado en vez de en variables de entorno en claro.
+
+Referencia de comandos del engine, esquema de `settings.json` y reglas de enrutado de modelos: [docs/AUDIT.md §4](../../docs/AUDIT.md) cubre la arquitectura; la sintaxis de `/goal`, `/workflow`, `/graph`, `/memory-*` y `/vault` está documentada inline vía `--help` y `/hotkeys` en el propio CLI.
+
+## Documentación
+
+- [Quickstart](docs/quickstart.md) — instalar, autenticar, ejecutar la primera sesión
+- [Usando Ada](docs/usage.md) — modo interactivo, slash commands, referencia del CLI
+- [Referencia TUI](docs/tui.md) — atajos de teclado completos, cola de mensajes, navegación del árbol
+- [Sesiones](docs/sessions.md) · [Compactación](docs/compaction.md) — branching, forking, gestión de contexto
+- [Settings](docs/settings.md) — configuración global y de proyecto
+- [Seguridad](docs/security.md) · [Containerización](docs/containerization.md) — confianza de proyecto, sandboxing
+- [Extensiones](docs/extensions.md) · [Skills](docs/skills.md) · [Prompt templates](docs/prompt-templates.md) · [Temas](docs/themes.md) · [Paquetes de Ada](docs/packages.md)
+- [SDK](docs/sdk.md) · [Modo RPC](docs/rpc.md) · [Modo JSON](docs/json.md) — uso headless y embebido
+- [docs/AUDIT.md](../../docs/AUDIT.md) — arquitectura del fork, mecánica de sync, y el análisis competitivo completo
+
+## Filosofía
+
+Ada se mantiene extensible en vez de opinada: sin MCP integrado por defecto (construye una skill o extensión en su lugar — [por qué](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/)), sin framework de sub-agentes forzado, sin popups de permisos, sin to-dos integrados. Construye exactamente lo que tu flujo necesita con [extensiones](docs/extensions.md), [skills](docs/skills.md), o un [paquete de Ada](docs/packages.md) de terceros — ver la [justificación original de pi.dev](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).
+
+## Contribuir y desarrollo
+
+Ver [CONTRIBUTING.md](../../CONTRIBUTING.md) y [docs/development.md](docs/development.md).
+
+## Licencia
+
+MIT
+
+## Ver también
+
+- [@earendil-works/pi-ai](https://www.npmjs.com/package/@earendil-works/pi-ai) — toolkit LLM base
+- [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core) — framework de agentes
+- [@earendil-works/pi-tui](https://www.npmjs.com/package/@earendil-works/pi-tui) — componentes de UI de terminal
+
+<p align="center">
+  El dominio <a href="https://pi.dev">pi.dev</a> fue donado generosamente por
+  <br /><br />
+  <a href="https://exe.dev"><img src="docs/images/exy.png" alt="Mascota Exy" width="48" /><br />exe.dev</a>
+</p>