specrails-desktop 2.44.2 → 2.46.0

package/docs/internals/agent-runtime-framework-evaluation.md

@@ -0,0 +1,208 @@
+# Evolución de Specrails hacia un runtime de agentes
+
+Análisis del 11 de septiembre de 2026. Recomendación arquitectónica basada en el código local y documentación oficial de los proyectos comparados.
+
+**Recomendación**
+
+Sí merece la pena pasar a una ejecución programática: Specrails debe decidir qué agente se ejecuta, con qué contexto, proveedor, herramientas, límites y evidencia de finalización. Recomiendo un runtime TypeScript compartido entre Core, Desktop y futuros workers. Conservaría el conocimiento y los controles de Specrails, y utilizaría componentes existentes para la infraestructura genérica.
+
+LangGraph.js es mi candidato preferido para el motor de workflows. Lo validaría con un piloto frente a un dispatcher TypeScript mínimo que reutilice el journal actual de Core. La adopción se justifica si simplifica de forma demostrable reanudación, interrupciones y coordinación de ramas; añadir otra máquina de estados para ejecutar las mismas seis fases no sería suficiente.
+
+Usaría `ai-agent-dev` como referencia de patrones y de un ejecutor Claude. No lo convertiría directamente en el motor general. Tampoco introduciría simultáneamente LangGraph, Mastra y otro supervisor de agentes. El objetivo es tener una autoridad clara para ejecutar el workflow.
+
+**Alcance y confianza del análisis**
+
+Se revisaron código, contratos, manifiestos, lockfiles, tests existentes y documentación de tres repositorios. `specrails-web` no se auditó funcionalmente: la decisión afecta principalmente a los tres componentes siguientes.
+
+| Repositorio | Versión local | Commit de referencia | Situación |
+| --- | --- | --- | --- |
+| ai-agent-dev | 0.40.4 | `2949748` | Sin cambios locales detectados al iniciar |
+| specrails-core | 5.1.0 | `2a8265e9` | Con cambios locales previos, incluidos runtime y su test |
+| specrails-desktop | 2.43.1 | `8bc84921` | Con cambios locales previos en varias áreas |
+
+Las conclusiones describen el checkout actual, no necesariamente los paquetes publicados. No se instalaron dependencias, ejecutaron modelos, consumieron API ni desplegaron servicios. En Core se ejecutó un subconjunto offline: `pipeline-state.test.ts`, `profile-schema.test.ts` y `profile-cli-validation.test.ts`, con 47 pruebas aprobadas en tres archivos. En Desktop pasaron otras 74 pruebas en cuatro archivos: `loop-graph.test.ts`, `loop-runs-store.test.ts`, `providers/registry.test.ts` y `providers/runtime.test.ts`. Son 121 pruebas aprobadas, no las suites completas. En ai-agent-dev se inspeccionaron las pruebas sin ejecutarlas: no tenía dependencias instaladas. Este documento es el único archivo creado por el análisis. Las ventajas de rendimiento propuestas son hipótesis para medir, no resultados de un benchmark de agentes.
+
+**El punto de partida real**
+
+Los tres repositorios ya contienen ejecución programática, con responsabilidades repartidas:
+
+| Componente | Lo que ya aporta | Lo que falta para el objetivo |
+| --- | --- | --- |
+| Core | Roles, OpenSpec, perfiles, contexto de repositorios, journal, gates y recibos reales de verificación | Un ejecutor común que lance agentes y controle el avance sin depender del coordinador LLM |
+| Desktop | Adaptadores, procesos, streaming, colas, loops, SQLite, costes, worktrees, MCP y entrega | Control homogéneo por fase; reanudación durable del grafo; política de proveedor por rol |
+| ai-agent-dev | Pipeline TypeScript con Claude Agent SDK, contexto preparado, JSON de análisis, herramientas y checks | Generalización, proveedores intercambiables, persistencia durable y garantías de ejecución |
+
+En Desktop, el pipeline principal sigue empaquetado en un único paso de IA. Su propio código lo explica: architect → developer → reviewer ocurre dentro de la invocación completa de Core. Eso limita qué puede observar y controlar el host en cada fase. [Grafo de Implement](/Users/javi/repos/specrails-desktop/server/loop-factory.ts:42).
+
+La migración debe conservar los prompts que expresan conocimiento de arquitectura, desarrollo y revisión. Las decisiones mecánicas —routing, siguiente fase, reintento, validación, presupuesto— deben tener una implementación ejecutable única.
+
+**Qué aporta ai-agent-dev**
+
+El servicio NestJS recibe eventos y crea Jobs Kubernetes. Hay tres variantes de agente para Android/múltiples ecosistemas, iOS y web. La variante se selecciona con reglas específicas de repositorios de Busuu. El inventario contiene 67 archivos fuente TypeScript, aproximadamente 13.875 líneas, y 33 archivos `.spec.ts`. [Dispatch del servicio](/Users/javi/repos/ai-agent-dev/service/src/webhook/webhook.service.ts:129).
+
+El flujo de la variante web es: ticket → clonación → mapa del repositorio → scout opcional → análisis estructurado → decisión por confianza → rama y OpenSpec → ejecución secuencial de tareas → pasos obligatorios → archivo de OpenSpec → checks y reparaciones → commit/PR → comentario. [Entrada](/Users/javi/repos/ai-agent-dev/agent-web/src/index.ts:223), [implementación](/Users/javi/repos/ai-agent-dev/agent-web/src/implement.ts:559).
+
+Reutilizaría estos patrones:
+
+- Preparar contexto con código antes de invocar IA: mapa de servicios y explorador económico cuando el tamaño lo justifica. [Mapa](/Users/javi/repos/ai-agent-dev/agent-web/src/repo-map.ts:1), [selección del scout](/Users/javi/repos/ai-agent-dev/agent-web/src/agent.ts:110).
+- Separar análisis y solicitud de aclaración en resultados estructurados. Añadiría validación estricta en runtime: el cast de TypeScript actual no valida el contenido recibido. [Schema](/Users/javi/repos/ai-agent-dev/agent-web/src/analysis-schema.ts:1), [consumo del resultado](/Users/javi/repos/ai-agent-dev/agent-web/src/index.ts:272).
+- Elegir modelos por fase y dar contexto acotado a cada tarea. Es selección estática; no demuestra optimización dinámica ni ahorro. [Opciones de análisis](/Users/javi/repos/ai-agent-dev/agent-web/src/agent.ts:206), [ejecutor de tareas](/Users/javi/repos/ai-agent-dev/agent-web/src/implement.ts:289).
+- Instrumentar fases con OpenTelemetry y asociar tokens y costes a las invocaciones. [Instrumentación](/Users/javi/repos/ai-agent-dev/agent-web/src/instrumentation.ts:21).
+- Extraer los adaptadores de toolchains y los checks útiles, eliminando dependencias de Jira, repositorios y releases internos.
+
+Hay limitaciones concretas que impiden tratarlo como un framework general terminado:
+
+| Hallazgo en el código | Implicación para Specrails |
+| --- | --- |
+| Claude Agent SDK declarado como `^0.3.148`; lockfile resuelve `0.3.217` | Acoplamiento a una implementación de agente, sin interfaz neutral de ejecución. [Lockfile](/Users/javi/repos/ai-agent-dev/agent/package-lock.json:36) |
+| `persistSession: false` en las consultas inspeccionadas | La continuación usa principalmente Git, artefactos y Jira; no hay checkpoint transaccional de fases. [Opciones](/Users/javi/repos/ai-agent-dev/agent-web/src/agent.ts:212) |
+| Al haber diez Jobs activos se omite crear otro | No hay cola durable ni reserva atómica; se puede perder trabajo. [Límite](/Users/javi/repos/ai-agent-dev/service/src/webhook/webhook.service.ts:166) |
+| Se captura coste, pero no existe un presupuesto global homogéneo | Turnos y timeout limitan ejecución, no garantizan gasto máximo. Hay una excepción puntual de presupuesto en Maestro. [Timeout](/Users/javi/repos/ai-agent-dev/agent-web/src/query-timeout.ts:10), [Maestro](/Users/javi/repos/ai-agent-dev/agent/src/maestro.ts:204) |
+| El caller de `fixQualityFailures` toma el coste e ignora el resultado final | Puede continuar hacia commit/PR con checks fallidos; además archiva OpenSpec antes de ejecutarlos. [Caller](/Users/javi/repos/ai-agent-dev/agent-web/src/implement.ts:682), [resultado del fixer](/Users/javi/repos/ai-agent-dev/agent-web/src/quality/index.ts:316) |
+| La terminación de tareas no discrimina todos los estados de error del SDK antes de marcarlas hechas | «Terminó la invocación» no equivale a «se cumplió la tarea». [Resultado](/Users/javi/repos/ai-agent-dev/agent-web/src/implement.ts:317), [marcado](/Users/javi/repos/ai-agent-dev/agent-web/src/implement.ts:669) |
+| Análisis con Bash, bypass de permisos y todo `process.env` | La intención de solo lectura del prompt no impone una frontera real; conservar el enforcement más fuerte de Desktop. [Configuración](/Users/javi/repos/ai-agent-dev/agent-web/src/agent.ts:206) |
+
+Otros hallazgos: el scout no entra en el total visible publicado del pipeline; `--branch` intenta consultar historial antes de clonar y la investigación puede empezar en la rama por defecto; hay módulos duplicados entre las tres variantes. Los checks iOS devuelven verificación no disponible fuera de macOS. Son motivos para extraer conceptos y módulos seleccionados, en vez de copiar toda la aplicación. [Scout](/Users/javi/repos/ai-agent-dev/agent/src/scout.ts:94), [continuación](/Users/javi/repos/ai-agent-dev/agent-web/src/index.ts:243), [checkout](/Users/javi/repos/ai-agent-dev/agent-web/src/implement.ts:575), [checks iOS](/Users/javi/repos/ai-agent-dev/agent-ios/src/quality/ios.ts:4).
+
+**Qué conservar de Core y Desktop**
+
+Core ya proporciona un contrato valioso: identidad de ejecución, specs congeladas, repositorios seleccionados y ownership de Git, backlog y worktrees. Su runtime escribe un journal atómico, ejecuta comprobaciones reales y vincula los recibos al contenido del candidato y al entorno. También determina qué fase ha quedado invalidada. Un framework genérico no sustituye estas reglas. [Contexto](/Users/javi/repos/specrails-core/src/installer/runtime/pipeline-state.ts:6), [gates y transiciones](/Users/javi/repos/specrails-core/src/installer/runtime/pipeline-state.ts:335), [reanudación lógica](/Users/javi/repos/specrails-core/src/installer/runtime/pipeline-state.ts:427).
+
+Pero este helper no ejecuta agentes: la coordinación principal sigue en plantillas distintas para Claude, Codex y Gemini; Kimi tiene un runner específico considerable. Existe incluso deriva entre el perfil validado y el prompt: schema/CLI permiten routing vacío o sin default, mientras el prompt Claude exige routing y exactamente un default. Centralizar esa decisión en código elimina una fuente de divergencia. [Operaciones del helper](/Users/javi/repos/specrails-core/src/installer/runtime/pipeline-state.ts:670), [schema](/Users/javi/repos/specrails-core/schemas/profile.v1.json:74), [validador CLI](/Users/javi/repos/specrails-core/bin/specrails-core.mjs:516), [prompt](/Users/javi/repos/specrails-core/templates/commands/specrails/implement.md:93).
+
+Desktop ya tiene contratos de capacidades y eventos para Claude, Codex, Gemini y Kimi. Hay transporte Codex app-server y Claude stream-json, además de ejecución por procesos. No hace falta reemplazar de golpe estos transportes para conseguir control programático. [ProviderAdapter](/Users/javi/repos/specrails-desktop/server/providers/types.ts:213), [ciclo común](/Users/javi/repos/specrails-desktop/server/spawn-lifecycle.ts:94), [sesiones vivas](/Users/javi/repos/specrails-desktop/server/providers/live-session.ts:5).
+
+Sus límites actuales ayudan a definir el piloto:
+
+- El motor de loops sigue un único sucesor; no implementa fan-out/join interno, aunque sí existe paralelismo entre ejecuciones aisladas. [Validación del grafo](/Users/javi/repos/specrails-desktop/server/loop-graph.ts:208).
+- Al reiniciar, los loops activos o pausados se marcan fallidos. La recuperación contable y del outbox es útil, pero no reanuda la continuación en memoria. [Reconciliación](/Users/javi/repos/specrails-desktop/server/loop-runs-store.ts:545).
+- En loops manda el proveedor/modelo del rail para todos los nodos. Core admite un proveedor global y modelos por agente dentro de él. Permitir proveedor distinto por rol requiere un contrato nuevo explícito. [Política del rail](/Users/javi/repos/specrails-desktop/server/loop-run-manager.ts:1465), [perfil v1](/Users/javi/repos/specrails-core/schemas/profile.v1.json:26).
+- El cap de coste del loop se comprueba entre pasos: puede excederse por un paso completo. Si el paso contiene todo Implement, el control es muy grueso. [Contrato del cap](/Users/javi/repos/specrails-desktop/server/loop-graph.ts:57).
+- El ledger ya diferencia consumo y estimaciones; el desglose por fase es principalmente reconstrucción de eventos Claude. Hay que medir desde cada invocación independiente. [Ledger](/Users/javi/repos/specrails-desktop/server/ai-invocations.ts:37), [desglose](/Users/javi/repos/specrails-desktop/server/job-phase-breakdown.ts:3).
+
+Mantendría worktrees, locks, alcance multirrepo, validación final de Core, MCP y entrega de PRs. [Preparación y finalización](/Users/javi/repos/specrails-desktop/server/core-execution.ts:48), [aislamiento](/Users/javi/repos/specrails-desktop/server/rail-isolation.ts:28), [control de herramientas](/Users/javi/repos/specrails-desktop/server/mcp/tools/types.ts:280).
+
+**Comparativa de alternativas**
+
+La tabla expresa mi valoración de encaje con este código, no una clasificación universal ni un benchmark de rendimiento.
+
+| Alternativa | Aportación y licencia comprobada | Encaje en Specrails |
+| --- | --- | --- |
+| LangGraph.js | Grafos con estado, checkpoints, streaming e interrupciones; biblioteca MIT | Primera opción para probar como motor embebido. Permite mantener nodos propios y ejecutores actuales. Exige diseñar almacenamiento, recovery y efectos externos. [Overview](https://docs.langchain.com/oss/javascript/langgraph/overview), [licencia](https://github.com/langchain-ai/langgraphjs/blob/main/LICENSE) |
+| Mastra | Framework TypeScript con agentes, workflows y suspensión/reanudación; núcleo Apache-2.0, directorios `ee/` con licencia distinta | Segunda opción. Atractivo para una aplicación nueva que necesite muchas piezas integradas; aquí existe solapamiento con producto y runtime de Desktop. [Workflows](https://mastra.ai/docs/workflows/overview), [licencias](https://github.com/mastra-ai/mastra/blob/main/LICENSE.md) |
+| Vercel AI SDK | Capa TypeScript multiproveedor, resultados estructurados y bucles de herramientas; Apache-2.0 | Útil si necesitamos llamadas API directas. Por sí solo no acredita reanudación durable de un workflow completo. Puede usar proveedores directos; no exige contratar el gateway. Revisar versión: el README actual exige Node 22+, mientras Specrails declara 20.19+. [Repositorio](https://github.com/vercel/ai), [licencia](https://github.com/vercel/ai/blob/main/LICENSE) |
+| OpenAI Agents SDK | Agentes, herramientas, handoffs y control del bucle en TS/Python; admite adapters para modelos externos | Viable, especialmente con inversión en OpenAI. No lo elegiría como autoridad de dominio; tampoco equivale a Codex. El host sigue siendo responsable de storage y decisiones de aprobación. [SDK](https://developers.openai.com/api/docs/guides/agents/sdk), [proveedores](https://developers.openai.com/api/docs/guides/agents/models) |
+| CrewAI | Crews y Flows en Python; MIT | Ofrece tanto colaboración autónoma como control explícito. No compensa introducir otro runtime/lenguaje para sustituir las piezas TS que ya existen. [Repositorio y licencia](https://github.com/crewAIInc/crewAI) |
+| Microsoft Agent Framework | Workflows y agentes, con foco documentado en .NET/Python; MIT | Más natural en un stack Microsoft. No es mi primera opción para el paquete npm y el sidecar actuales. Para un desarrollo nuevo no partiría del AutoGen anterior: su repo dirige a migración. [Framework](https://github.com/microsoft/agent-framework), [AutoGen](https://github.com/microsoft/autogen) |
+
+LangGraph puede usarse como biblioteca sin adoptar la plataforma alojada de LangSmith. Su persistencia necesita un checkpointer durable: el de memoria pierde estado al reiniciar. La documentación presenta SQLite para uso local/desarrollo y PostgreSQL como alternativa; la adecuación de SQLite al producto de escritorio debe verificarse con concurrencia, WAL, bloqueo y pruebas de caída. [Persistencia](https://docs.langchain.com/oss/javascript/langgraph/persistence).
+
+Mastra también persiste snapshots de workflows y puede guardar estado de suspensión en almacenamiento configurado. No lo descartaría por carecer de estas capacidades. Lo situaría detrás de LangGraph por la cantidad de responsabilidades que Specrails ya tiene resueltas. [Snapshots de Mastra](https://mastra.ai/docs/workflows/snapshots).
+
+**El ejecutor de programación es una decisión distinta**
+
+Un cliente de modelos devuelve texto o llamadas a herramientas. Un ejecutor de programación también administra archivos, edición, shell, herramientas, contexto, permisos y sesiones. Reemplazar un CLI por una llamada a un modelo no reproduce automáticamente ese comportamiento.
+
+| Ejecutor posible | Valor para Specrails | Decisión recomendada |
+| --- | --- | --- |
+| Adaptadores actuales + Claude Agent SDK / Codex SDK o app-server | Aprovechan herramientas y sesiones de programación ya conocidas | Primera etapa. Exponerlos detrás de `AgentExecutor`; modernizar transporte donde aporte una mejora concreta. [Claude SDK](https://code.claude.com/docs/en/agent-sdk/overview), [Codex SDK](https://learn.chatgpt.com/docs/codex-sdk) |
+| OpenCode | Coding agent MIT, proveedores múltiples y cliente JS/TS para controlar un servidor | Buen candidato a ejecutor neutral posterior. Probar calidad, permisos, lifecycle del proceso y empaquetado antes de convertirlo en dependencia. [Licencia](https://github.com/anomalyco/opencode), [SDK](https://opencode.ai/docs/sdk/), [proveedores](https://opencode.ai/docs/providers/) |
+| Deep Agents | Harness sobre LangGraph, con contexto, herramientas y subagentes, y ejemplos multiproveedor | Alternativa si queremos una implementación de agente más controlada por Specrails. Añade otra migración: probar separadamente del motor de fases. [Documentación JS](https://docs.langchain.com/oss/javascript/deepagents/overview) |
+| OpenHands Software Agent SDK | SDK MIT con APIs Python, TypeScript y REST; workspace local o Agent Server con entornos efímeros | Interesante para workers de desarrollo aislados. Evaluar su arquitectura/operación; no descartarlo por asumir que solo ofrece Python. [Repositorio](https://github.com/OpenHands/software-agent-sdk) |
+
+LiteLLM resuelve otra capa: gateway de APIs, routing, balanceo y alternativas de proveedor. Lo consideraría si Specrails opera workers compartidos y necesita centralizar credenciales y límites. No lo impondría a cada instalación de Desktop ni lo usaría para orquestar fases. Su código base tiene licencia MIT con partes sujetas a licencia comercial. [Gateway](https://github.com/BerriAI/litellm), [failover](https://docs.litellm.ai/docs/proxy/reliability), [licencia](https://github.com/BerriAI/litellm/blob/litellm_internal_staging/LICENSE).
+
+**Arquitectura propuesta**
+
+```mermaid
+flowchart TD
+    Entry[Desktop / CLI / worker] --> Runtime[Runtime compartido TypeScript]
+    Core[Core: roles, specs, reglas y gates] --> Runtime
+    Runtime --> Workflow[Motor de ejecución reemplazable]
+    Workflow --> Executors[AgentExecutor por fase]
+    Executors --> Native[Claude / Codex / Gemini / Kimi]
+    Executors --> Neutral[Ejecutor neutral o herramientas + API]
+    Runtime --> Store[Estado durable y eventos]
+    Runtime --> Policy[Presupuesto, permisos y capacidades]
+    Runtime --> Host[Servicios del host: worktrees, checks y entrega]
+    Store --> UI[Proyecciones para la UI y analítica]
+```
+
+Empezaría como módulo o paquete dentro del ecosistema actual, sin crear obligatoriamente un cuarto producto o repositorio. Debe poder consumirse sin Electron/Tauri, React o un Desktop arrancado. Core standalone conserva su CLI; Desktop actúa como host. Jira/Kubernetes de `ai-agent-dev` serían adaptadores de entrada y ejecución remota opcionales.
+
+Los contratos clave serían:
+
+- `AgentDefinition`: rol, versión de instrucciones, schemas de entrada/salida y capacidades requeridas.
+- `AgentExecutor`: ejecutar, cancelar, consultar capacidades y reanudar si el transporte lo soporta; emite eventos normalizados.
+- `ProviderPolicy`: proveedor/modelo por rol, credencial referenciada, esfuerzo y alternativas permitidas. Separar proveedor de inferencia del tipo de ejecutor.
+- `RunContext`: scope congelado, repositorios, referencias a artefactos, ownership actual de Core y versiones de workflow, Core y definiciones de agentes.
+- `StepResult`: estado explícito (`succeeded`, `failed`, `blocked`, `cancelled`, `needs_recovery`), resultado validado, recibos y consumo.
+- `BudgetPolicy`: tiempo, tokens, turnos, coste y concurrencia. Lo desconocido se registra como desconocido.
+- `HostServices`: filesystem/worktrees, runner de comprobaciones, aprobaciones, publicación y backlog.
+
+No trasladaría un historial interno de Claude a Codex como si fuera una sesión portable. Un cambio de proveedor entrega un paquete neutral de artefactos, resultados y estado del workspace. El executor solo anuncia resume nativo cuando existe.
+
+**Cómo evitar dos máquinas de estado en conflicto**
+
+Core debe seguir definiendo las reglas de validez del trabajo. El motor elegido decide scheduling y continuidad; los ejecutores solo ejecutan un rol. Desktop conserva UI, admisión de jobs, concesión de recursos y servicios del host; deja de planificar las fases del camino migrado. El runtime solo puede repartir workers dentro de la concurrencia y presupuesto concedidos por el host. Durante el piloto, cada ejecución pertenece a un único motor: el nuevo camino invoca roles acotados y nunca ejecuta `/implement` completo dentro de otro workflow.
+
+En el piloto conservador, el journal de Core es la autoridad: cada inicio o reanudación consulta `inspectPipeline`, y ningún checkpoint puede saltar sus gates. Si se adopta un motor durable como destino, se extraen los gates como políticas y la persistencia del motor controla la ejecución; el journal público pasa a ser una proyección compatible. El helper CLI debe delegar en ese coordinador para los runs migrados, en lugar de escribir el mismo estado por su cuenta.
+
+Un coordinador único valida el gate de Core, registra el recibo de la fase y publica un evento. Las tablas de estado que usa Desktop son proyecciones. Si la transición mantiene temporalmente varios almacenes, se necesitan revisiones monotónicas, correlación de eventos y reconciliación explícita ante una caída entre escrituras. Sincronizar dos JSON después de cada nodo no resuelve el problema. Además, la reanudación siempre debe comprobar que el candidato y sus evidencias siguen vigentes.
+
+Para efectos externos —PRs, commits, cambios de estado— usar identidad estable por ejecución/paso y comprobar qué ocurrió antes de repetir. Conservar y ampliar el patrón de outbox existente. Un checkpoint no revierte cambios en Git, no resucita un proceso y no garantiza ejecución exactamente una vez de una API remota.
+
+La pausa humana debe sobrevivir al reinicio. Una fase interrumpida a mitad de edición requiere comprobar el worktree y el último recibo: reanudar la sesión cuando sea posible o pasar a recuperación explícita. No basta con repetir ciegamente el nodo. Los reintentos del motor son infraestructura, no prueba de que una operación sea segura para repetir. [Políticas de retry y timeout](https://docs.langchain.com/oss/javascript/langgraph/fault-tolerance).
+
+Actualizar Desktop o Core no debe hacer que un checkpoint antiguo continúe sobre un grafo incompatible. Cada run congela versiones; el runtime exige compatibilidad, migración explícita o recuperación. Al reanudar también se revalidan los permisos actuales: mantener la identidad de una aprobación no restaura capacidades revocadas o caducadas.
+
+**De dónde puede venir la eficiencia**
+
+1. Quitar del contexto LLM validaciones de perfil, routing mecánico, preparación de ramas y decisiones de control ya expresables en código.
+2. Entregar a cada rol el contexto que necesita: specs y mapa para arquitectura; tareas y archivos concretos para desarrollo; diff, criterios y recibos para revisión.
+3. Reutilizar resultados cuya identidad de candidato/contexto siga vigente. Invalidarlos cuando cambie el código, la spec o el entorno relevante.
+4. Elegir inicialmente modelos por rol mediante reglas simples y perfiles versionados. Escalar capacidad tras un fallo clasificado, con límite; no introducir un agente supervisor que decida cada transición trivial.
+5. Paralelizar solo trabajo independiente, en workspaces compatibles. Dos desarrolladores editando los mismos archivos necesitan coordinación y validación del resultado integrado.
+6. Reservar presupuesto antes de despachar y reconciliar consumo real después. Un límite global requiere coordinar invocaciones concurrentes. Con APIs se puede limitar mejor cada llamada; con algunos CLIs solo se ve el total al terminar, de modo que no prometería un cap monetario exacto.
+7. Instrumentar todas las invocaciones, incluidos scout, retries, reparaciones y síntesis. Separar costes reportados, estimados y no disponibles.
+
+La métrica principal debe ser coste por spec aceptada, acompañada de calidad y tiempo humano. Menos tokens con más errores no es una mejora; más agentes tampoco implica más eficiencia. Cambiar SDK y política de modelos a la vez impediría atribuir el resultado a una causa.
+
+**Plan de migración y criterio de decisión**
+
+| Etapa | Entregable | Criterio para avanzar |
+| --- | --- | --- |
+| 1. Contratos y línea base | Ejecutores, eventos, errores y ownership; métricas actuales sobre un conjunto de tareas | Poder observar invocaciones y fases sin depender de inferencias del texto |
+| 2. Piloto de ejecución | Un flujo explícito arquitectura → desarrollo → verificación → revisión → corrección limitada → archivo; entrega del host | Mismas garantías de Core y pruebas de caída/reanudación |
+| 3. Comparar motores | Implementar el flujo con dispatcher mínimo y con LangGraph, usando los mismos ejecutores y fixtures | Elegir LangGraph si reduce código especial de recovery/coordinación sin degradar empaquetado y compatibilidad |
+| 4. Migración gradual | Flag por ejecución/proyecto; Core CLI y Desktop consumen el mismo runtime; los jobs antiguos terminan en su motor | Ninguna ejecución es reclamada por dos motores; rollback por nuevas ejecuciones |
+| 5. Proveedores por rol | Perfil nuevo con capacidades, límites y alternativas; SDKs donde aporten valor | Cambio de proveedor comprobado sin perder scope, permisos, trazabilidad ni calidad |
+| 6. Escala opcional | Workers, gateway y almacenamiento remoto si el producto lo necesita | Demanda operativa demostrada; no requisito para uso local |
+
+El piloto debe pasar, al menos, estas pruebas verificables:
+
+- Matar el proceso después de desarrollo y continuar en verificación/revisión sin regenerar arquitectura ni repetir una fase válida.
+- Matarlo durante una edición y recuperar el workspace de forma explícita; no certificar como terminado lo que solo tiene logs parciales.
+- Pausar para aprobación, reiniciar y resolver esa misma aprobación sin perder su identidad.
+- Actualizar el runtime con un run pausado y detectar incompatibilidad de versiones; revocar un permiso antes de reanudar y bloquear el siguiente efecto que lo requiera.
+- Simular 429, timeout y credencial inválida: diferenciar fallo transitorio, límite de cuenta y error permanente; aplicar retry acotado. Un fallback tras resultado ambiguo debe reconciliar efectos.
+- Unir dos trabajos independientes y verificar el candidato integrado; rechazar escrituras fuera de los repositorios seleccionados.
+- Impedir archivo/finalización si los checks obligatorios fallan o si su recibo ya no describe el candidato actual.
+- Repetir un callback y reiniciar entre intención/confirmación de PR sin duplicar publicación ni contabilizar dos veces.
+- Comprobar cancelación del árbol de procesos, bloqueo de SQLite, empaquetado y compatibilidad Windows/macOS/Linux, incluyendo Node y dependencias nativas.
+
+Después haría una evaluación pequeña y emparejada, por ejemplo 15–20 specs representativas, ejecutadas desde el mismo commit base. Esa cifra es una propuesta de trabajo, no un tamaño estadístico que garantice una conclusión. Primero mantener modelo y herramientas constantes para medir el cambio de orquestación; después probar modelos por rol. Registrar éxito aceptado, regresiones, coste total, duración, reintentos, contexto repetido, checks redundantes y minutos de intervención humana. No se ha realizado esa evaluación en esta investigación.
+
+Si el dispatcher existente consigue los mismos resultados con menos complejidad, lo mantendría. La frontera `WorkflowEngine` permitiría introducir LangGraph más adelante. Lo que recomiendo adoptar desde el principio es el control explícito y compartido de ejecución.
+
+**Qué significa gratuito y open source en esta decisión**
+
+Es posible ejecutar el núcleo MIT de LangGraph localmente sin contratar una plataforma de orquestación. Las otras alternativas de la tabla tienen licencias y componentes propios; los productos cloud o Enterprise no deben confundirse con sus bibliotecas abiertas. Las licencias se han consultado como metadatos técnicos; no constituyen un análisis jurídico.
+
+Las llamadas a modelos siguen consumiendo API, cuotas de una suscripción o recursos de hardware. Un modelo local evita facturación por token a un proveedor, pero requiere infraestructura y validar su calidad. Tampoco convierte un framework abierto en un stack completamente abierto si depende de un ejecutor propietario.
+
+En particular, que `ai-agent-dev` declare MIT no convierte Claude Agent SDK en MIT: su lockfile remite a otra licencia y la documentación oficial remite a términos comerciales. Puede ser un adaptador opcional de un runtime abierto. [Lockfile](/Users/javi/repos/ai-agent-dev/agent/package-lock.json:36), [licencia y términos del SDK](https://code.claude.com/docs/en/agent-sdk/overview#license-and-terms).
+
+Para autenticación, recomiendo modelar ambos caminos —cuenta local del usuario y API— sin asumir que son intercambiables. La documentación de Claude contiene un matiz relevante: el artículo de soporte indica que se pausó el cambio anunciado de consumo de suscripción, mientras la documentación del SDK limita ofrecer login/límites de claude.ai en productos de terceros sin aprobación previa. Eso no permite prometer a usuarios de Specrails acceso programático incluido por defecto. Mantener los transportes existentes no resuelve por sí mismo la elegibilidad del producto. [Actualización del plan](https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan), [integración del SDK](https://code.claude.com/docs/en/agent-sdk/overview).
+
+La decisión inmediata propuesta es invertir en un piloto de runtime compartido, tomando LangGraph.js como candidato externo principal y el journal actual como base de comparación. Aprovechar los patrones de `ai-agent-dev`, los contratos de Core y los servicios de Desktop permite avanzar con una migración acotada y medir antes de comprometer una reescritura.

package/docs/internals/programmatic-agent-runtime-validation.md

@@ -0,0 +1,72 @@
+# Programmatic agent runtime: implementation verification
+
+Validated locally on **2026-09-11**, on macOS with Node 25.9.0. The complete paired execution was also validated with Desktop's bundled **Node 22.23.1**. This records the paired source implementation in Specrails Core and Desktop; it is not a published release or a Windows runner result.
+
+## Result
+
+Core owns a typed LangGraph workflow for architecture, development, deterministic verification, review, bounded corrections and archive. Provider adapters execute individual roles. Desktop admits the configured workflow into its existing scoped worktree/rail execution and exposes configuration, progress, durable continuation, approval and cancellation.
+
+The supported built-in transports are Claude, Codex, Gemini, Kimi and an OpenAI-compatible HTTP tool loop. A programmatic executor registry supports additional providers without changing the workflow. The new orchestration infrastructure is free and open source; existing model services and local hardware retain their own costs and terms.
+
+## Automated checks
+
+| Check | Result |
+| --- | --- |
+| Core full coverage suite | 50 files passed; 750 tests passed, 1 skipped |
+| Core coverage | 90.86% lines, 86.44% statements, 79.63% branches, 93.23% functions |
+| Desktop server/CLI full coverage suite | 336 files passed, 2 skipped; 8,276 tests passed, 7 skipped |
+| Desktop server/CLI coverage | 89.36% lines, 86.67% statements, 79.66% branches, 90.64% functions |
+| Desktop client full coverage suite | 390 files passed; 4,877 tests passed |
+| Desktop client coverage | 90.04% lines/statements, 84.28% branches, 76% functions |
+| TypeScript | Core and Desktop typechecks passed |
+| Builds | Core build; Desktop server, client, CLI and MCP bridge builds passed |
+| Script regressions | Core 19 and Desktop 75 tests passed |
+| Core npm package | Actual tarball installed in an unrelated consumer; both CLI entries, four provider assemblies, runtime export/declarations and a LangGraph execution passed |
+| Desktop npm package | Actual tarball installed in an unrelated consumer; CLI, assets, schemas and compiled CommonJS-to-external-Core-CLI negotiation/validation passed, including simulated pkg execution without bundled Node |
+| Paired source assembly | Locked Core production dependencies staged in `src-tauri/core`; offline workflow smoke passed |
+| Complete paired workflow | Compiled Desktop bridge → real Core CLI → localhost HTTP tool fixture → real verification → approval → archive passed on Node 25.9.0 and bundled Node 22.23.1; two resumes preserved completed roles, usage and Git ownership |
+| Sidecar bundle | Server esbuild bundle using the native build's CJS/Node 22 options passed |
+| New Desktop portability job | Workflow passed `actionlint`; its exact eight-suite command passed 111 tests locally on macOS |
+| Existing Core compatibility | Desktop 2.43.1 and the locally selected installed Core 5.2.3 passed the existing contract check |
+
+All existing coverage thresholds remained enabled. The client suite initially hit an unrelated AddProjectDialog timeout under concurrent heavy builds; its isolated suite and a complete rerun with two workers passed. Server tests that bind localhost were run with the required execution permissions after sandbox-only `EPERM` failures.
+
+The Desktop full coverage figures above precede the final Node-launcher fallback fix. After that fix, the eight affected suites passed 105 tests, typecheck and the server build passed again, and the final installed-package plus paired Node 22 checks passed. The resolver preserves the running interpreter in ordinary Node, prefers a bundled interpreter when available, and uses PATH `node` from a packaged server whose bundled Node is missing. The new portability job also includes its regression suite.
+
+The installed Core compatibility check preserves the legacy contract. The new API was separately exercised against the **paired source Core** through its installed package, assembled bundle and Desktop's compiled loader; an older published package is not evidence that API 1 is present.
+
+## Live provider runs (2026-09-11, macOS, Claude Sonnet via the installed CLI)
+
+Two end-to-end runs on a throwaway Node repository (`node --test`) using the source Core CLI directly, before and after the second round of changes:
+
+| Run | Configuration | Outcome |
+| --- | --- | --- |
+| live-01 (previous runtime) | Claude for all roles, verification configured | Failed after 2 min and $0.18: the developer had no shell, left a "run the tests" task unchecked, and the verify step aborted the workflow with "Required implementation tasks remain incomplete" |
+| live-02 (current runtime) | Claude for all roles, **no verification configured** | Succeeded in 72 s for $0.33: the architect proposed `npm test`, the developer ran the tests in its sandbox and ticked all six tasks, verification ran the proposed command, the reviewer approved with score 96, archive completed |
+
+The same failure shape was reproduced by a user on a greenfield HTML project (a manual browser checklist task the developer could not tick). The changes that address it: developer tool parity with the legacy Implement step, optional/architect-proposed verification with admitted unverified repositories, unchecked tasks routed back as developer feedback, architect instructions that forbid manual or delivery tasks, session reuse on correction passes, native structured output with one in-session repair turn, readable phase notes instead of raw JSON in the log, and a fresh attempt budget on explicit resume.
+
+## Behavioral evidence
+
+- Offline workflow tests exercise success, correction limits, configuration identity, exclusive leases, persisted approvals, process interruption, explicit recovery, evidence invalidation and archive crash reconciliation.
+- Core rejects invalid verification repository IDs/paths and known unsupported provider limits before any role executes. Injected executors declare their own limit capabilities.
+- Provider tests exercise structured CLI events, old Kimi ACP plan mode, scoped tools, cancellation, incomplete responses, Windows argument handling and a real localhost OpenAI-compatible coding fixture. A local Kimi 0.27 capability probe initialized ACP and selected plan mode without submitting a model prompt.
+- Gemini and Kimi ACP return the final assistant turn separately from tool-progress commentary. Gemini's native policy engine was also checked locally across 36 decisions with plan disabled and existing broad user approvals: only the designated read-only tools remained allowed. System policies that disable the per-run policy cause an explicit capability failure.
+- Desktop integration tests execute real child processes and verification commands, validate final Core identity/evidence, preserve interrupted worktrees and retain original scope when resuming.
+- `node scripts/smoke-agent-runtime-pair.mjs` additionally exercises the actual compiled Desktop/Core boundary against a deterministic local HTTP model fixture. The fixture edits only its temporary repository through Core tools and validates the complete approval/archive flow.
+- Desktop adopts Core's paused-question contract: `pendingQuestion`, `traceId` and step `visits` from `status --compact`, `resume --answer`, tighten-only review thresholds (70/75/60 floors) and `architect.onLowConfidence`, plus tolerant parsing of `span` events. Unit tests cover the `answer_required` gate, the answer argv, the bridge's question-aware pause message and the memoized API probe.
+- Continuation accounting reuses the existing durable recovery ledger. Replayed events do not duplicate usage; unavailable cost or token values remain unknown. Recovery also handles interrupted continuations before accepting another one.
+- Core's existing CI matrix runs the new tests on macOS, Windows and Linux with Node 20.19.0, 22 and 24. Desktop adds focused runtime integration coverage on macOS and Windows. These remote jobs have not been dispatched from this session.
+
+## Remaining release and operational limits
+
+1. **Changes are local source, not a published release.** The production Desktop registry lock still pins Core 5.1.1; the local Core checkout identifies itself as 5.1.0. Publish and pin a reviewed paired Core release before distributing Desktop. Do not downgrade an activated managed Core installation to try this source feature; use the documented explicit development runtime override.
+2. **Native Windows and live paid-provider execution remain unverified here.** Windows paths, process shims and protocol contracts have automated coverage, but native Windows execution must pass on its runner. No paid inference was invoked during implementation.
+3. **Enable projects explicitly.** The runtime applies to implementation rail steps. Mission chat and other unrelated AI features keep their existing transports. A role still needs central model instructions; workflow ordering, gates, retries and archive are code-owned.
+4. **Resume preserves host delivery boundaries.** A resumed Core workflow finishes in the original worktree. It does not automatically restart the former rail's PR/backlog delivery phase. The normal uninterrupted rail retains its existing delivery flow.
+5. **Capabilities differ by provider.** Native dollar caps are available only for the built-in Claude executor. Kimi has no authoritative usage counters, and old ACP versions cannot expose every multi-repository read-only scope. Gemini read-only roles require enforceable native admin policies. Unsupported configurations fail explicitly. Local endpoints need function tool support.
+6. **Archive uses complete reviewed specifications.** It replaces the corresponding main specification documents; it does not merge partial OpenSpec deltas.
+
+A production dependency audit also found two high-severity advisories in the pre-existing `fast-uri` 3.1.0 and `js-yaml` 4.1.1 entries. Those exact versions were already in Core's original lockfile; the new runtime dependencies did not introduce them. This implementation does not claim a clean baseline dependency audit.
+
+See [setup and recovery](programmatic-agent-runtime.md), [architecture evaluation](agent-runtime-framework-evaluation.md), and the paired Core checkout's `docs/agent-runtime.md` for configuration and programmatic APIs.

package/docs/internals/programmatic-agent-runtime.md

@@ -0,0 +1,140 @@
+# Programmatic agent runtime
+
+Desktop can hand implementation to Core's **runtime API 1**. Core runs architect, developer, deterministic verification, reviewer and archive as separate LangGraph phases. Desktop keeps project/worktree selection, rail lifecycle, logs, accounting and delivery ownership.
+
+This is the only implementation engine in the current source tree. It applies to implementation rail steps and their Core completion check. Mission chat and unrelated AI features keep their existing transports. Provider-native implementation prompts and skills are not invoked inside the programmatic phases.
+
+## Build the paired source
+
+Use Node **20.19.0+** for Core; Node **22.22.3** matches Desktop's native CI runtime. Provider requirements can be higher. Both repositories' dependencies must be installed.
+
+```sh
+cd ../specrails-core
+npm ci
+npm run build
+npm run check:package
+cd ../specrails-desktop
+npm ci
+npm ci --prefix client
+node scripts/assemble-bundled-core.mjs --source ../specrails-core
+npm run dev
+```
+
+The assembly command stages the built Core checkout into `src-tauri/core`, installs its locked production dependency closure, and runs an offline workflow smoke test. It can download npm dependencies; it does not invoke an AI provider. Build Core first and repeat assembly after changing its runtime. Native development uses `npm run dev:desktop` instead of `npm run dev`; stop the existing app first and follow the [native development instructions](../../README.md#develop-from-source).
+
+To verify the complete paired execution boundary without paid model calls:
+
+```sh
+npm run build:server
+node scripts/smoke-agent-runtime-pair.mjs
+```
+
+This runs the compiled Desktop bridge and real bundled Core against a temporary localhost model fixture. It checks tool writes, a real verification subprocess, archive approval, resume, usage and host Git ownership. It uses a temporary repository and deletes it afterward. Pass `--core /absolute/path/to/Core/dist/agent-runtime/index.js` to exercise another built Core checkout.
+
+For web development, an explicit runtime override can point to the built module:
+
+```sh
+# macOS shell, from specrails-desktop
+export SPECRAILS_CORE_RUNTIME_PATH="$PWD/../specrails-core/dist/agent-runtime/index.js"
+npm run dev
+```
+
+```powershell
+# PowerShell, from specrails-desktop
+$env:SPECRAILS_CORE_RUNTIME_PATH = (Resolve-Path ../specrails-core/dist/agent-runtime/index.js).Path
+npm run dev
+```
+
+Use this override when an activated managed or globally installed Core is newer than the source bundle and does not yet expose API 1. Merely assembling an older-version checkout does not override Desktop's selected installation. Keep its installation/lifecycle selection intact while testing the explicitly selected execution module.
+
+The override identifies **index.js**, not the package directory or CLI file. Runtime discovery checks it first, then the existing Core resolver's selected installation, including activated managed updates. An authoritative managed, override or bundled installation is not silently replaced when its runtime is missing or incompatible. Production does not fall back to a sibling checkout. Development can also resolve an installed `specrails-core/agent-runtime` export or a sibling Core build when no authoritative runtime is available.
+
+Desktop negotiates `runtime api` and sends configuration to `runtime validate --stdin` through its bundled/system Node interpreter. This keeps the Core ESM runtime outside Desktop's CommonJS/pkg process and avoids relying on unsupported dynamic imports inside the native sidecar.
+
+`SPECRAILS_CORE_RUNTIME_PATH` selects this execution module. The existing `SPECRAILS_CORE_BIN` controls the installation/lifecycle resolver and is a different setting. Prefer a paired source bundle when testing the complete installation and execution flow.
+
+## Configure a project
+
+1. Open **Project settings → Agent runtime** (its own section in the project dialog).
+2. Choose a provider per role. The model dropdown lists each CLI's catalog with the default marked; turns, attempts and timeout show their defaults in the fields. Claude, Codex, Gemini and Kimi remain available; open **General settings → Specrails Agents → Provider connections** to add an OpenAI-compatible endpoint for a local or remote model (local endpoints do not require a key; API providers need an explicit model).
+3. Verification commands are optional. A project that never saved runtime settings is prefilled with the checks Desktop detects offline (`package.json` test/type-check/lint scripts with the right package manager, Cargo, Go, pytest, Gradle, Maven, .NET, Make); **Detect project checks** re-runs that detection. Each row is a repository plus one command line (`npm run test -- --strict`; quotes group arguments). Leave the list empty and the architect proposes the project's own checks on each run; repositories with no automated check are still reviewed and recorded as unverified in Core's receipt.
+4. **Review gate** and **Architect confidence** are optional. Review thresholds (overall score and the five aspects: type correctness, pattern adherence, test coverage, security, architectural alignment) can only *tighten* Core's own gate: the floors are 70 overall, 75 for security and 60 for every other aspect, and Desktop rejects lower values before saving (`Review threshold review.minScore must be at least 70 (Core's own review gate)`). Empty fields omit the key so Core's defaults apply. `architect.onLowConfidence` decides what happens when, after one autonomous investigation pass, the architect's design is still low in confidence: `ask` (default) pauses the run with the architect's question; `proceed` continues on stated assumptions.
+5. Save the project settings. Implementation always uses the agent runtime.
+6. Start an implementation through the normal rail flow.
+
+Settings are saved at `<project execution .specrails directory>/agent-runtime.json`. Missing configuration uses the default agent runtime. The retired enabled flag cannot select another engine. Malformed configuration blocks admission; it is not ignored. Saving verifies that Core exposes the expected API. Connections are stored globally in `~/.specrails/runtime-providers.json`; project files retain role references, models, limits and verification. Existing embedded connections migrate once, with stable disambiguated IDs on endpoint conflicts. New runs freeze the resolved configuration, while saved runs retain their original snapshot.
+
+Core owns role instructions and permissions. The developer role edits and runs commands inside its CLI sandbox (the same autonomy as the legacy Implement step); architect and reviewer are read-only. A legacy rail profile/model selection does not override the runtime's per-role provider configuration. The JSON schema is [server/schemas/agent-runtime.schema.json](../../server/schemas/agent-runtime.schema.json), mirrored from Core. For a complete configuration, custom executor examples, Kimi capabilities and API tooling details, see [Core's runtime guide](https://github.com/fjpulidop/specrails-core/blob/main/docs/agent-runtime.md) in the paired revision.
+
+The built-in Claude adapter supports its native dollar cap. Built-in Codex, Gemini, Kimi and OpenAI-compatible adapters reject `maxCostUsd`; remove that limit for mixed-provider/local runs. Kimi also rejects token caps because its usage is unavailable. Unknown cost/tokens remain unknown in accounting, rather than becoming zero. Attempt, timeout and tool limits remain available. Existing provider services, licenses and inference costs are separate from the free open-source orchestration runtime.
+
+Gemini architect/reviewer roles require native `--admin-policy` support. Core applies a temporary read-only tool allowlist that remains effective if user settings disable plan mode. If system policies prevent per-run enforcement, Core rejects that role with an actionable capability error; it does not replace managed policies. The developer role retains its normal editing transport.
+
+## State, approvals and continuation
+
+The rail creates a frozen Core execution context for its original repository/worktree paths. State is kept below the project's execution `.specrails/pipeline/<runId>/` directory:
+
+| File | Purpose |
+| --- | --- |
+| `desktop-context.json` | Selected repositories, original worktrees, frozen scope and ownership |
+| `desktop-runtime-config.json` | Admission snapshot of project settings with verification commands restricted to the selected repositories; project settings remain unchanged |
+| `desktop-runtime-host.json` | Allowlisted host settings needed to reconstruct execution |
+| `agent-runtime-request.json` | Core's frozen configuration and change name |
+| `state.json`, `receipts/` | Core gates and verification receipts |
+| `agent-workflow/<runId>/checkpoint.json` | Durable phases, attempts, approvals and usage |
+
+A run pauses (Core exit code 2) either on an **approval** (`pendingApproval`, for example before archive) or on a **question** (`pendingQuestion: { stepId, requestedAt, question }`) when the architect is configured to ask on low confidence. A pending question can only be resumed together with an answer: the runs panel shows the question with a textarea and an **Answer and resume** action, which posts `{ "answer": "…" }` (nonempty, at most 20,000 characters). Resuming without an answer while a question is open is rejected with `400 answer_required`. Once Core records `answeredAt`, the question is history and ordinary resume applies again. The bridge reports a paused run's reason in the job log: awaiting approval, or the pending question text.
+
+**Implementation cards and job detail** expose resume, archive approval, question answering, interrupted-step recovery and continuation cancellation actions next to the work. Cards query their latest job by original rail identity; job detail queries its exact run. Legacy jobs render no runtime panel. **Jobs → Saved executions** retains the cross-run history. Project settings contain runtime configuration only. A continuation resumes from the phase shown, in the original worktree, and writes its progress into that job's log (a `[runtime] continuation started from phase …` banner, tool activity, phase notes and the final outcome). Resuming a run that stopped at the developer attempt limit grants a fresh attempt budget. Wait for the original rail execution to settle before resuming. Active rail jobs are stopped through their job controls; the continuation's Cancel action owns only continuations started from this panel.
+
+Resume retains valid completed phases and rechecks Core evidence. Changed code or environment requires fresh verification/review. An ambiguous interrupted write requires an explicit recovery action after inspecting partial changes. A changed frozen config/identity requires a new run. Missing original worktrees or mismatched execution manifests block recovery; the controller never invents a replacement worktree.
+
+Saved executions link directly to the original job log. Continuations broadcast readable logs and raw runtime events to that job, publish `runtime.continuation` lifecycle updates, and reserve the original implementation card until settlement. Jobs list/detail project the continuation as running while it is active (including the running filter); the failed attempt remains in history. Job and card cancellation route to the continuation process. After a successful continuation, Desktop revalidates Core receipts, commits the exact preserved worktrees locally, and reconciles the job and repository delivery cards to completed / ready for review. A new completion event supersedes the earlier failed summary while retaining the failed attempt and its usage. The activity reservation then clears.
+
+**A continuation prepares local delivery for review after Core succeeds; it does not create a PR or merge code.** Use the normal delivery card actions to review and publish. Older successful continuations expose **Prepare delivery**, which performs the same receipt validation and local settlement without invoking a model. This also applies when approval is granted after the original rail has settled. Core archive success is not a claim that a PR was created. The initial uninterrupted successful rail retains its normal host delivery flow.
+
+Disabling project runtime settings affects future admission. Existing runs retain their frozen runtime request and remain available for explicit continuation; they do not switch back to a platform prompt.
+
+## API and logs
+
+All routes are under `/api/projects/:projectId`:
+
+| Method/path | Result |
+| --- | --- |
+| `GET /agent-runtime/config` | Saved/default config and runtime availability |
+| `PUT /agent-runtime/config` | Validate and atomically save configuration |
+| `GET /agent-runtime/runs` | Recent run status, `traceId`, pending approval or question, recoverable phases and available controls |
+| `POST /agent-runtime/runs/:runId/resume` | Accept `{}`, `{ "approve": ["archive"] }`, `{ "recover": ["developer"] }`, explicit `invalidate` phase IDs, or `{ "answer": "…" }` for a pending question (required while one is open) |
+| `POST /agent-runtime/runs/:runId/cancel` | Cancel a continuation owned by this controller |
+
+Resume responds `202` after admission and continues asynchronously. The valid phase IDs are `architect`, `developer`, `verify`, `reviewer` and `archive`. Core's lease remains the cross-process concurrency guard. A run cannot be resumed while its original Desktop execution is active.
+
+Desktop launches `node <Core>/dist/agent-runtime/cli.js` with structured argv (`--approve`, `--recover`, `--invalidate`, `--answer <text>` on resume) and consumes JSON lines for phase events (`workflow-event`), agent output (`agent-event`), verification output, trace spans (`span`: `{ traceId, spanId, name, stepId, attempt, visit, startedAt, endedAt, status, usage?, error? }`) and the terminal `runtime-result`. Spans are stored verbatim as job events for diagnostics and are not narrated in the log. `runtime status --compact` returns `state.traceId`, `pendingApproval`, `pendingQuestion` and per-step `{ status, visits }`. Desktop probes `runtime api` once per Core CLI file revision (path plus mtime/size); `runtime validate --stdin` runs on every save. The job log shows phase transitions (`[runtime] step_started: developer`), live tool activity per role (`[developer] Read src/app.ts`, `[developer] Bash npm test`) and Core's own phase notes (architecture written, verification passed, review approved or corrections requested); the final JSON of architect and reviewer is not echoed. The narrated view (Relato) derives its milestones from the same events: each runtime phase, the tools used, correction loops and a stopped workflow with Core's structural reason. Accounting uses the invocation's new attempts, so resuming a completed phase does not bill its cumulative history twice. Status queries use `--compact`, are read-only and do not invoke providers; accumulated logs stay in Core's checkpoint instead of overflowing the process status response.
+
+Provider invocation/cancellation supports native macOS processes and Windows executables/npm shims. Actual provider behavior still depends on the installed CLI version and capabilities. The offline tests cover fake CLI/ACP frames, Windows argv rules, a local HTTP coding fixture and real verification subprocesses; live provider smoke tests and Windows CI remain separate validation.
+
+## Rollout and release pairing
+
+The committed registry bundle lock and `CORE_BUNDLE_VERSION` currently pin **Core 5.1.1**, a previously published package. That pin does not incorporate these source changes. Source assembly is the supported development route until the paired Core runtime release is available.
+
+A production release must:
+
+1. Publish a reviewed Core package containing API 1, `dist/agent-runtime/` and its production dependencies.
+2. Update `scripts/assemble-bundled-core.lock.json` and `CORE_BUNDLE_VERSION` together to that exact release, capturing the full dependency integrity closure.
+3. Run Core package checks, Desktop compatibility/package checks and both macOS/Windows native validation before packaging the paired app.
+
+Do not relabel an old 5.1.1 bundle or copy only `dist/agent-runtime`: LangGraph and the complete runtime dependency closure are required. Source assembly writes `source-bundle.json` with the Core version, runtime API and lock hash for traceability; it does not publish Core or update the production registry lock.
+
+Verify role outputs, delivery ownership and saved-run recovery before releasing the paired app. Implementation has no legacy fallback; profile v1 remains only for other workflows. Core's programmatic archive writes reviewed **complete specification replacements**; it does not merge partial OpenSpec delta snippets. Preserve unchanged requirements in the architect's output and inspect that behavior during the pilot.
+
+See [Core runtime selection and recovery](core-runtime-updates.md) for the separate framework-update lifecycle and [the original evaluation](agent-runtime-framework-evaluation.md) for the architecture rationale.
+
+The [implementation verification record](programmatic-agent-runtime-validation.md) lists the completed checks and outstanding release validation.
+
+## Efficiency metrics
+
+Core's additive runtime metrics v1 are passed from compact status to each saved run's optional `metrics` field. The contextual run panels and Jobs history render a collapsed **Usage and time** panel with reported cost, active execution/agent time, calls and token/cache totals, plus per-phase attempts, duration, provider calls and cost. All eight locales include the panel labels.
+
+Older Core versions continue to work without the panel. The server validates numeric fields and known phase IDs, drops unsupported/malformed metrics and projects only the supported fields; it never forwards arbitrary transcripts from the metrics object. Missing billing is displayed as unavailable rather than zero. Cache tokens are already included in input tokens, and agent duration already includes native tool work. The panel does not estimate savings or measure implementation quality.
+
+The paired `agent-runtime-efficiency` OpenSpec change in specrails-core documents verification ownership, efficient API tools and the measurement contract. Core exposes the same report through `runtime status` / `runtime-result`, so a fixed set of real tasks can be compared without a Desktop database migration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.44.2",
+  "version": "2.46.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/agent-mcp-config.js

@@ -266,6 +266,11 @@ function codexMcpOverrides(entry) {
     const args = [
         ...c(`mcp_servers.specrails.command=${JSON.stringify(entry.command)}`),
         ...c(`mcp_servers.specrails.args=[${entry.args.map((a) => JSON.stringify(a)).join(', ')}]`),
+        // This invocation owns a server-minted capability. Specrails authorizes
+        // each action against its mission tier; Codex's tool-level prompt cannot
+        // distinguish facade reads from writes and fails under approvalPolicy=never.
+        // Keep this scoped to the internal bridge, never external MCP servers.
+        ...c('mcp_servers.specrails.default_tools_approval_mode="approve"'),
     ];
     for (const [k, v] of Object.entries(entry.env)) {
         args.push(...c(`mcp_servers.specrails.env.${k}=${JSON.stringify(v)}`));

package/server/dist/agent-operator-prompt.js

@@ -79,8 +79,8 @@ repository members, and runs coordinated AI coding pipelines over their selected
   routing). Supported by Claude and Kimi; forced to null on Codex/Gemini rails.
 - **Provider / engine** — claude, codex, gemini or kimi. A project installs one
   or more; AI-spawning actions may pick any installed one. Claude and Kimi
-  support profiles and Freestyle; Contract Refine and SMASH require Claude's
-  structured-action boundary. Persistent interactive jobs remain Claude-only.
+  support profiles and Freestyle; Contract Refine supports Claude and Codex
+  (read-only). SMASH and persistent interactive jobs remain Claude-only.
   Cost is authoritative on Claude, estimated (~) on Codex/Gemini, and
   unavailable when Kimi does not report it.
 

package/server/dist/agent-runtime-accounting.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseProgrammaticUsage = parseProgrammaticUsage;
+const SETTLED_STEPS = new Set(['step_succeeded', 'step_failed', 'step_blocked', 'step_paused', 'step_interrupted']);
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+const known = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+/** Recover one Core invocation's accounting from raw stdout event payloads.
+ * A terminal invocation total already includes its phase events and wins over
+ * them. Without that frame, an unfinished attempt makes inclusive totals
+ * unknown: costs from completed phases alone would be misleadingly precise. */
+function parseProgrammaticUsage(rawRows) {
+    let recognized = false;
+    let terminal;
+    const seen = new Set();
+    const started = new Set();
+    const settled = new Set();
+    const usages = [];
+    for (const row of rawRows) {
+        let frame;
+        try {
+            frame = JSON.parse(row);
+        }
+        catch {
+            continue;
+        }
+        if (!object(frame))
+            continue;
+        if (frame.type === 'runtime-result') {
+            recognized = true;
+            terminal = frame;
+            continue;
+        }
+        if (frame.type === 'agent-event') {
+            recognized = true;
+            continue;
+        }
+        if (frame.type !== 'workflow-event' || !object(frame.event))
+            continue;
+        const event = frame.event;
+        if (typeof event.id !== 'string' || typeof event.type !== 'string')
+            continue;
+        recognized = true;
+        if (seen.has(event.id))
+            continue;
+        seen.add(event.id);
+        const attempt = typeof event.attemptId === 'string' ? event.attemptId : typeof event.stepId === 'string' ? event.stepId : event.id;
+        if (event.type === 'step_started')
+            started.add(attempt);
+        if (SETTLED_STEPS.has(event.type)) {
+            settled.add(attempt);
+            usages.push(object(event.usage) ? event.usage : {});
+        }
+    }
+    if (!recognized)
+        return undefined;
+    let usage = {};
+    if (object(terminal?.invocationUsage)) {
+        usage = terminal.invocationUsage;
+    }
+    else if (usages.length > 0 && [...started].every((attempt) => settled.has(attempt))) {
+        for (const key of ['costUsd', 'inputTokens', 'outputTokens']) {
+            const values = usages.map((item) => known(item[key]));
+            if (values.every((value) => value !== undefined))
+                usage[key] = values.reduce((sum, value) => sum + value, 0);
+        }
+    }
+    const cost = known(usage.costUsd), tokensIn = known(usage.inputTokens), tokensOut = known(usage.outputTokens);
+    return {
+        provider: 'agent-runtime', model: 'per-role', cost, tokensIn, tokensOut,
+        tokens: tokensIn === undefined || tokensOut === undefined ? undefined : known(tokensIn + tokensOut),
+        estimated: cost === undefined, failed: terminal?.status !== 'succeeded',
+    };
+}