Bienvenida. Esta es una versión técnica de Arvantti Harness®, pensada para equipos de desarrollo. Vamos a ver la arquitectura real del repositorio arv-harness: el Core en TypeScript, la CLI como frontera estable, los adapters, las terminales con node-pty y xterm, el Brain sobre SQLite + sqlite-vec y la Shell de escritorio en Electron. Arvantti Harness® es marca registrada de Arvantti Labs, una marca de Sequoia Space.

Cuatro dolores concretos. 1) Los modelos no guardan estado entre turnos: el harness reenvía system prompt, definiciones de tools y MCP, metadatos de skills, CLAUDE.md/AGENTS.md y todo el historial; el costo acumulado de una sesión crece O(n²). 2) El prompt caching funciona por prefijo idéntico byte a byte (orden: tools → system → mensajes). Agregar o quitar tools, cambiar de modelo o de agente, o compactar, rompe el prefijo y se reprocesa todo lo posterior. Añadir contenido al final no lo rompe. 3) Subagentes y sesiones que comparten contexto o checkout se contaminan. 4) Sin un control plane común no hay registro de quién hizo qué. Fuente: ADR-0002 y ADR-0003 (contexto/caché) y la nota de diseño exploratoria ARVANTI-resumen-completo.md, que no es canónica.

Así funciona el arnés de arneses. A la izquierda, los harnesses o CLIs de código con IA que ya usa tu equipo: Claude Code, Antigravity, GPT Codex, OpenCode, Kimi, Pi, Gemini, Microsoft Copilot o modelos locales. Cada uno se conecta mediante un adapter delgado, que traduce sus acciones y delega en la CLI estable de Arvantti; el adapter no tiene lógica de negocio ni es fuente de verdad de capacidades (ADR-0001). En el centro está el Core de Arvantti Harness®, común para todos: policy (qué se permite), grants (permisos por sesión), tasks (trabajo trazable), receipts (evidencia en NDJSON), brain (contexto y memoria) y guardianes de rutas y secretos. El Core opera sobre tu entorno: repositorios, terminales reales (PTY, pseudo-terminales), conectores y archivos. Arvantti no inhabilita los subagentes, tools ni flujos nativos de cada harness (ADR-0003): los envuelve con un mismo control plane.

Lectura de arriba hacia abajo: una petición entra por un host (Electron Desktop, la TUI, el adapter Pi con /arvantti o tu propia shell), cruza la CLI estable (bin/arvantti.mjs → src/cli: parseCliArgs, executeCli, formatCliResult) y llega al Core (src/core: project-policy, guardians, grant-document, task-contract, task-receipt, work-intake, session-assignments, brain-repository, context-measurement…). El Core no hace I/O ni contiene un loop LLM: los adapters (src/adapters: pi, terminal con node-pty y buffer ANSI, brain con sqlite-vec, obsidian-vault para SDD, local-store en .arvantti/, transcript, process) hacen el trabajo con efecto. Hay un adapter por cada harness de código con IA (Pi, Claude Code, Antigravity, GPT Codex, OpenCode, Kimi), siempre delgado y delegando en la CLI. La capa de ejecución son PTYs reales (pseudo-terminales: consolas reales creadas por programa, con node-pty), worktrees autorizados y procesos foreground. Desktop, TUI y CLI no son autoridades de permisos; la policy se revalida en la frontera del efecto. Cloudflare (ADR-0010, hito H16) será gestión, gobernanza y conocimiento compartido, nunca host de ejecución.

Preferimos CLI sobre MCP: cada servidor MCP agrega definiciones de tools al prefijo del contexto, lo infla y rompe el caché al activarlo o quitarlo; la CLI se invoca por bash, que todos los harnesses ya tienen, y devuelve salida paginada, redactada y auditable. ADR-0002: la CLI es la frontera estable para humanos, agentes y adapters. Evita registrar una tool nativa por cada integración (lo que inflaría el prefijo y rompería el caché) y obliga a respuestas paginadas, redactadas y aptas para entrar al final del contexto. Los 11 comandos que existen hoy están en src/cli/command.ts: help, version, catalog, pull, policy, task, flow, plan, sdd, shell y tui; --json cambia el formato de salida. Sintaxis real: plan assess <summary> [--steps=N] [--reversible] [--external-effect] [--sensitive] [--architecture] [--uncertain] [--multi-actor] [--force=direct|task|sdd-lite|sdd-full]; sdd create --level=lite|full --id=ARV-SDD-#### <slug> <title>; sdd inspect <bundle>; task <create|claim|complete> <task-id> [title]; task link <task-id> <sdd-id> <sdd-path>; pull <profile|skill|flow|integration> <id> <revision> (requiere ARVANTTI_SUBJECT_ID); policy <shared|local> <path>; flow code-review <revision>. Los IDs del ejemplo (T-12, ARV-SDD-0042) son ilustrativos. Ojo: comandos como "arvantti brain search" o "arvantti skill show" aparecen en ADR-0002 como ejemplos futuros y aún no existen. Riesgo asumido: bash no es sandbox; la CLI valida argumentos, rutas y scopes.

Aviso: el marco de esta diapositiva viene de la nota exploratoria ARVANTI-resumen-completo.md, que NO es canónica; lo canónico es ADR-0002, ADR-0003 y el subplan de arquitectura agéntica. 01 Prefijo estable: ADR-0003 fija el perfil nativo de tools/MCP al inicio de sesión; cambiarlo en vivo es excepción explícita con impacto de caché documentado. Las asignaciones por sesión están implementadas; medir caché con Pi real sigue pendiente (H2/H3), por eso Parcial. 02 Punteros lazy: diseño de tres niveles catálogo → flujo → instrucciones por agente; mantener la cadena plana (2 niveles es robusto). Implementado: arvantti catalog y arvantti pull con assignments y receipts (ARV-US-0010). 03 Inyectar al final: pull por CLI implementado; el modo context-push existe como tipo de asignación pero el flujo normal es pull por check-in, sin inyectar trabajo en una sesión activa. 04 bash + CLI: el adapter Pi delega en la CLI (ARV-US-0008). Presupuesto: context-budget.json declara maxItems, maxCharacters, maxTokens opcional (heurística ceil(bytes UTF-8 / 4), no tokenizer real) y la política de overflow paginate/summarize/reject; el pull local rechaza contenido que excede en lugar de truncarlo.

Además hay coordinación multiagente: cada agente trabaja en su terminal y comparten tareas y receipts. Y un Room de concilio, un espacio donde los agentes contrastan sus propuestas y concilian una decisión antes de actuar, con la persona como árbitro final. Cada agente en su propia terminal/sesión, con su contexto y, si escribe código, su propio worktree: así no se contaminan. El árbol de decisión viene de la nota exploratoria (no canónica): evaluar en orden y detenerse en la primera respuesta decisiva; prioridad corrección (1–2) > capacidad (3) > optimización (4). Dato de pruebas del autor en esa nota: Pi arranca con ~800–1.000 tokens de entrada y Claude Code con ~20.000, así que con arneses livianos abrir terminales separadas es barato. PTY (pseudo-terminal) quiere decir una terminal real creada por programa: el agente cree estar en una consola normal y Arvantti puede ver lo que entra y sale. PTY embebido local con node-pty, buffer ANSI con @xterm/headless, tabs, menú contextual y restauración estructural en la TUI (ARV-SDD-0024); grupos jerárquicos y bindings persistidos en .arvantti/terminal-workspace.json; al restaurar, las sesiones aparecen como unknown y nunca se relanzan solas (ARV-US-0016). La terminal es libre: no exige policy ni grants y NO es sandbox; Arvantti no controla un pi o claude que tú lances ahí. Desktop Electron tiene PTY real, tabs múltiples, splits recursivos y reattach tras recargar el renderer. Worktrees: el Core tiene contrato de binding; crear el primer worktree o rama requiere autorización humana explícita (ADR-0004). El Canvas de relaciones entre sesiones (ARV-SDD-0025) está planificado.

Ventajas de esta arquitectura: es privada y puede vivir en el equipo, en una nube local o en la nube privada de la empresa, sin que los datos salgan de ese entorno; es un solo archivo, sin un servidor de base de datos que operar; guarda texto (FTS5) y vectores (sqlite-vec) en la misma base, así que la búsqueda híbrida no exige sincronizar dos sistemas; y los respaldos son triviales con VACUUM INTO. Además, como el dominio va por puertos, se puede proyectar a la nube sin cambiar a los agentes. El cerebro empresarial es memoria en grafo: qué se sabe, qué se decidió y qué ocurrió, siempre con procedencia y temporalidad. Modelo lógico (architecture/brain-data-model.md): Project, Knowledge source y revision (procedencia y digest), Document y chunk, Brain snapshot (separado de commit y dirty delta), Entity, Claim y Relation (con confianza y vigencia), Evidence (locator seguro + digest), Decision (qué, quién y con qué evidencia), Actor, Embedding profile y Vector reference. ADR-0005 (aceptado): SQLite nueva + sqlite-vec local para Brain V1; se descartan PostgreSQL y Neo4j por coste operativo prematuro y el híbrido por complejidad de sincronización. sqlite-vec sirve sólo al índice vectorial detrás de VectorIndexPort; el dominio va por BrainRepositoryPort y BrainQueryPort. node:sqlite es experimental en Node 22. Cloudflare D1/Vectorize serían una proyección Cloud futura, no la fuente de verdad. Estado ARV-US-0012: parcial. Las tareas viven en la capability Tasks (implementada) y las decisiones pendientes como entidad Brain están en el modelo, aún sin CLI de consulta. Comandos como "arvantti brain search" son diseño futuro, no existen todavía.

Arvantti Harness® le da a la IA tres cerebros. Uno, el brain de proyecto: la memoria del proyecto, con sus SDD, tareas, documentos y contexto, para que cada agente arranque sabiendo dónde está el trabajo. Dos, el graph brain de decisiones: un grafo de quién decidió qué, cuándo y con qué evidencia, incluidas las decisiones pendientes. Tres, understanding repo: un grafo de código con el mapa de funciones, módulos y dependencias del repositorio, para que la IA entienda el código de una pasada. En lugar de leer archivo por archivo, el agente consulta el mapa: gasta menos tokens, se equivoca menos y propone mejores cambios. Todo vive en el Brain local, con procedencia, y los agentes lo consultan por puertos y CLI.

Work Intake / SDD Resolver (src/core/work-intake.ts, ARV-US-0003) recomienda uno de cuatro métodos a partir de señales explícitas y neutrales al harness. Reglas reales: SDD completo si hay decisión de arquitectura, 8 o más pasos, o 3 o más señales entre efecto externo, sensibilidad de seguridad, incertidumbre material y múltiples actores; además recommendsAdr. SDD Lite si hay incertidumbre, varios actores, efecto externo o sensible, o 4 o más pasos. Directo sólo si es exactamente un paso y --reversible. Si no, Task. La recomendación nunca crea una Task ni un SDD, no concede permisos y no sustituye la policy; --force=direct|task|sdd-lite|sdd-full registra tu elección. Después, la creación es explícita: arvantti sdd create --level=lite|full --id=ARV-SDD-#### <slug> <title> (ARV-US-0013 y 0014). El SDD completo es una nota primaria más siete fases: brief, spec, design, tasks, execution, verify y closing. arvantti sdd inspect <bundle> detecta drift de IDs y lifecycle sin escribir Markdown, y arvantti task link conserva a Task como autoridad. Todo es Markdown Obsidian-native: frontmatter YAML, wikilinks y carpetas normales. El flujo Task ↔ SDD con receipts se verificó end-to-end (ARV-SDD-0017).

Historia de usuario de keys: si un agente intenta leer, mostrar o cambiar una API key (por ejemplo en un archivo .env), la ruta y la operación pasan por el guardián; los secretos requieren autorización humana explícita (ADR-0004), y cualquier valor con forma de secreto que aparezca en la salida se reemplaza por [REDACTED] antes de llegar a transcripts, receipts o logs. Cadena real de autorización (src/core/guardians.ts y project-policy.ts). 01 authorizeProjectPath normaliza léxicamente la ruta: debe ser relativa al proyecto y sin traversal; sólo después se evalúa policy, y el llamador sólo abre la ruta tras un allow. 02 Policy compartida (.arvantti/policy.shared.json) más override local restrictivo (policy.local.json); un override local nunca elimina restricciones. 03 Grants en .arvantti/grants.json: vinculan sujeto, proyecto, recurso y operación, y se revocan; en V1 no caducan solos. Las operaciones con efecto (EffectOperation) son las seis de la línea en monoespaciado. 04 redactOutput sanea recursivamente la salida antes de transcript, receipts o logs: literales configurados y asignaciones con forma de secreto se sustituyen por [REDACTED]; es defensa de salida, no autoriza leer un secreto. Parcial porque falta la conexión persistente completa a Room/log (ARV-US-0007). Hay además un dependency guardian para pnpm. ADR-0004: continuous safe permite editar, stage y commit dentro de una tarea y un worktree ya autorizados; la primera rama o worktree, merge, push, PR, borrados, secretos, red o MCP externo, deploy y publicación requieren autorización humana explícita.

Arvantti Harness® trabaja con loops de agentes. El loop de desarrollo planea con SDD, implementa, prueba y revisa, y vuelve a empezar hasta cerrar la tarea. En paralelo corre el loop de seguridad: agentes que vigilan archivos y salidas, detectan keys y datos sensibles, bloquean la lectura de archivos .env y otros secretos, y redactan la salida y avisan a una persona cuando algo intenta salirse. Así, mientras unos agentes construyen, otros cuidan que ninguna key ni dato sensible se escape. Los loops se apoyan en los guardianes, la policy y los grants de la diapositiva anterior.

Los receipts son registros append-only, independientes del TODO de cada harness. TaskReceipt (src/core/task-receipt.ts): schemaVersion, receiptId, taskId, projectId, actorId, action (created | claimed | completed | linked), status y recordedAt; se persisten como NDJSON en el local-store. PullReceipt (pull-receipt.ts): receiptId, assignmentId, sessionId, target (id y revisión), deliveredAt, outcome delivered | rejected y summary. Los IDs técnicos son UUID v7 estables, independientes de rutas y títulos. También existe un receipt de transcript redactado y observaciones de contexto; su persistencia completa sigue en curso (ARV-SDD-0007 en ejecución). En roadmap (ARV-US-0025): una CLI de auditoría liviana, append-only y filtrable para cambios que Git no cubre (SDD, Design MD, decisiones Brain, configuración agéntica), con modelo declarado, reportado o unknown; fallar un log advierte sin bloquear, y nunca se afirma un receipt que no sea durable. Sobre ISO/IEC 42001: decirlo con cuidado. La trazabilidad está pensada para apoyar prácticas de gestión de IA alineadas con la norma; Arvantti no está certificado ni certifica a nadie.

Aunque preferimos CLI, Arvantti también tiene una capa MCP nativa: los clientes y harnesses que trabajan con MCP pueden conectarse directamente, siempre detrás de la misma policy, los mismos grants y el mismo registro. La tabla viene de la nota exploratoria (no canónica), escenario Zoho: si activas un MCP nativo a mitad de sesión, sus tools entran al prefijo y el historial se reprocesa al activar y otra vez al desactivar. Si Arvantti conecta el MCP, envía la lista de comandos como mensaje y el agente los usa por bash a través de la CLI: el caché queda intacto; al desactivarlo, Arvantti deja de aceptar esos comandos y avisa. Bonus: las credenciales viven en Arvantti y cada llamada queda registrada. Lo canónico (master plan §11 y subplan agéntico): MCP es integración/adaptador, no núcleo de orquestación; la decisión es CLI-first local y MCP queda limitado a proveedores externos futuros, detrás de adapter, policy y consentimiento; red/MCP externo es siempre human gate. Hitos: H10 (Code Intelligence, LSP y MCP local acotado) y A8 del subplan agéntico (paquetes opcionales/MCP/servicios externos con ADR, threat model, consentimiento, coste y rollback por integración).

Los adapters conectan cada harness de código con IA (Pi, Claude Code, Antigravity, GPT Codex, OpenCode y Kimi) y delegan en la CLI local de Arvantti. Historia de la decisión: ADR-0006 proponía una Web Shell local-first como interfaz principal y la TUI como secundaria; ADR-0007 y ADR-0009 la acompañaban. Las tres quedaron sustituidas por ADR-0011: Electron Desktop es la primera Shell gráfica y la Web queda para Cloudflare, sin terminal. Desktop (apps/desktop, Electron 45 + xterm 6, preview de desarrollo, ARV-SDD-0037/0038): el PTY y los efectos privilegiados viven en el main process; el preload es mínimo y el IPC se autoriza por sender, frame y origen. Hay CSP verificada, control de flujo con ACK y watermarks (ráfagas de 270 KB y 1 MB en pruebas E2E), cierre con confirmación agregada, reattach tras recargar el renderer y un soak de 5 minutos. Tras relanzar la app se restauran metadatos y layout, nunca procesos. No hay instalador, firma ni updater. TUI: arvantti tui y arvantti shell; quedan pendientes streaming, permisos, resize y cancelación end-to-end. La lógica compartida no se duplica por plataforma. ADR-0008: toda Shell funcional debe tener un PTY real; los mocks sólo valen para diseño o tests aislados.

ADR-0001: cada harness entra como adapter delgado (Pi, Claude Code, Antigravity, GPT Codex, OpenCode, Kimi), nunca como Core ni como fuente de verdad de capacidades o policy. Los ADR viven en el vault de documentación (Arvantti-Harness/adr). 0004: continuous safe dentro de tarea, worktree y rama ya autorizados; la primera creación de worktree o rama, merge, push y acciones destructivas requieren autorización. 0005: SQLite + sqlite-vec para Brain V1, con D1/Vectorize como proyección Cloud futura. 0008: una Shell gráfica sin PTY real no es entregable. 0010: Cloudflare es gestión, gobernanza y conocimiento compartido, nunca host de terminales, PTYs ni comandos. 0011: Electron Desktop primero; no se construye ahora una Web Shell local con Connector. 0012: nada de forks por sistema operativo, sólo adapters pequeños con contrato común.

Cierre para equipos técnicos: invitamos a una demo de la CLI, de la TUI y de la preview Desktop, o a proponer un adapter para el harness que use tu equipo. Contacto: Andrés Quiceno, CTO de Ingeniería, [email protected]. Web: arvantti.tech. LinkedIn: Arvantti Labs y Sequoia Space Latam. Arvantti Harness® es marca registrada de Arvantti Labs, una marca de Sequoia Space.