# Codex Suite en Cursor Mobile Bridge Manual operativo y técnico. Actualizado el **23 de julio de 2026, 00:49:32 (Europe/Madrid, UTC+02:00)**. Documentos canónicos: - [Estado real y hoja de control](CODEX-SUITE-STATUS.md): completado, parcial, pendiente y siguiente orden de ejecución. - [Plan de producto y negocio](CODEX-SUITE-BUSINESS-PLAN.md): visión y estrategia futura; no describe por sí solo capacidades implementadas. Las secciones 13 y 19 conservan contexto y evidencia histórica. Para saber qué existe ahora prevalece `CODEX-SUITE-STATUS.md`. ## 1. Qué es Codex Suite es una aplicación alojada dentro de `cursor-mobile-bridge`. No sustituye al bridge ni a sus demás aplicaciones. La relación es: ```text Cursor Mobile Bridge :8095 ├── /apps Lanzador de 47 accesos ├── /hub Hub existente ├── /manager System Manager ├── /ops IA Ops ├── /codex-suite Cliente web de Codex ├── /api/codex/* Backend protegido de Codex └── Codex App Server Proceso local por stdio ``` El navegador nunca inicia procesos ni ejecuta herramientas directamente. La UI llama al backend del bridge, el backend valida la sesión y el workspace, y solo entonces envía métodos JSON-RPC a `codex app-server`. ## 2. URLs En el PC: ```text http://127.0.0.1:8095/codex-suite http://127.0.0.1:8095/apps ``` Por Tailscale: ```text http://IP_TAILSCALE_DEL_PC:8095/codex-suite http://IP_TAILSCALE_DEL_PC:8095/apps ``` Si MagicDNS está activo: ```text http://NOMBRE_DEL_PC.ts.net:8095/codex-suite ``` Codex Suite usa el mismo servidor que `/apps`. No hay que exponer otro puerto ni iniciar App Server en una dirección remota. App Server permanece detrás del bridge mediante `stdio`. ## 3. Acceso desde Tailscale 1. Mantén el bridge escuchando en `0.0.0.0:8095`. 2. Conecta el PC y el móvil a la misma tailnet. 3. Abre `/apps` usando la IP Tailscale o MagicDNS del PC. 4. Pulsa `Codex Suite`. 5. Introduce `BRIDGE_TOKEN` en el diálogo de inicio de sesión. 6. El token se envía una sola vez por `POST /api/codex/session`. 7. El servidor devuelve una cookie `HttpOnly`, `SameSite=Strict`. No incluyas el token en favoritos, URLs, capturas ni mensajes. Si un token apareció anteriormente en una URL, debe rotarse en `.env` y reiniciarse el bridge. ## 4. Lanzador de aplicaciones El catálogo `config/equipitello-apps.json` contiene 47 accesos. Es normal que el número sea mayor que las carpetas de primer nivel de `C:\xampp\htdocs`: un proyecto puede publicar varios frontends, paneles, agentes, APIs o accesos profundos. Codex Suite está registrado como: ```json { "id": "codex-suite", "port": 8095, "path": "/codex-suite", "category": "Dev" } ``` El lanzador calcula una URL local y una URL Tailscale para cada entrada. Por tanto, el mismo acceso funciona desde el PC, LAN o Tailscale sin duplicar Codex Suite ni convertir el bridge en una aplicación exclusiva de Codex. ## 5. Autenticación ### Flujo recomendado ```text Token en diálogo -> POST /api/codex/session -> comparación en tiempo constante -> cookie codex_session HttpOnly -> llamadas /api/codex autenticadas ``` La cookie: - no es legible desde JavaScript; - no se guarda en `localStorage`; - usa `SameSite=Strict`; - expira tras 12 horas de inactividad renovada; - usa `Secure` cuando el bridge recibe HTTPS. Las mutaciones verifican el mismo origen. La compatibilidad temporal con `X-Bridge-Token` existe para clientes antiguos del bridge, pero Codex Suite usa la cookie. ## 6. Workspace y seguridad de herramientas Antes de crear un thread se selecciona un workspace permitido. El catálogo solo incluye rutas bajo: - `HTDOCS_ROOT`; - raíces adicionales declaradas en `EXTRA_PROJECT_PATHS`. Se usa la ruta real del sistema de archivos para impedir escapes mediante junctions o enlaces simbólicos. Modos disponibles: | Modo | Lectura | Escritura | Red | |---|---:|---:|---:| | Solo lectura | Workspace | No | No | | Escritura en workspace | Workspace | Solo workspace | No | La UI no ofrece `danger-full-access`. Los comandos y cambios sensibles generan solicitudes de aprobación. La aprobación de permisos nunca amplía el acceso de archivos o red fijado por el bridge. Las rutas adjuntas al compositor deben: - ser relativas al workspace; - existir; - resolver dentro de la ruta real del workspace. ## 7. Threads y turns Un thread es una conversación persistente. Un turn es una petición y el trabajo que Codex realiza para atenderla. Operaciones gráficas: - crear thread; - abrir y reanudar historial; - crear chat lateral efímero; - bifurcar un thread; - renombrar; - compactar contexto; - definir un objetivo persistente; - archivar; - eliminar con confirmación; - cancelar un turno; - añadir una instrucción a un turno activo mediante `turn/steer`. El borrado exige escribir `ELIMINAR` y el backend exige además que el identificador de confirmación coincida con el thread. ## 7. Panel Control — guía operativa El hub Control tiene cuatro grupos (Operar / Proyecto / Calidad / Sistema) y dieciséis pestañas. La referencia **cuándo / cómo / por qué** de cada una, junto con la matriz de verificación (API smoke vs UI) y la explicación de **qué modelo se está usando**, está en: → [CODEX-SUITE-CONTROL-GUIDE.md](CODEX-SUITE-CONTROL-GUIDE.md) Estado del lab EQUIPITELLO ↔ servidor IA `.16`: → [MIGRACION-EQUIPITELLO-16-STATUS-2026-08-08.md](MIGRACION-EQUIPITELLO-16-STATUS-2026-08-08.md) ## 8. Modelos y ejecución El panel `Control > Recursos` obtiene los modelos de `model/list`. No mantiene una lista de modelos escrita a mano. Al elegir un modelo se actualizan: - esfuerzos de razonamiento soportados; - service tiers disponibles; - disponibilidad de personalidad. El modelo, esfuerzo, velocidad, personalidad y modo de permisos se envían al backend al iniciar el turno. Los modos **Consultar** y **Planificar** fuerzan además el sandbox `readOnly`, aunque el selector general esté en escritura. Plan vuelve a Agente después de enviarse para que un plan aprobado no deje accidentalmente bloqueados los turnos posteriores. **Auto · predeterminado** delega la selección al modelo efectivo de App Server; no cambia de proveedor de manera arbitraria durante un turn. En móvil se mantiene visible el modelo y el botón **Opciones** agrupa esfuerzo, tier y personalidad. Esto reduce la altura inicial del compositor sin retirar ninguna capacidad. ## 9. Skills, MCP, apps, plugins y hooks El panel de recursos consulta App Server: | Recurso | Método | |---|---| | Modelos | `model/list` | | Skills | `skills/list` | | MCP | `mcpServerStatus/list` | | Apps de Codex | `app/list` | | Plugins | `plugin/list` | | Hooks | `hooks/list` | | Límites | `account/rateLimits/read` | | Perfiles de permiso | `permissionProfile/list` | El navegador recibe metadatos reducidos. No recibe comandos de hooks, rutas privadas de plugins, esquemas completos de herramientas ni tokens. Una skill seleccionada se adjunta como entrada nativa `type: "skill"` al siguiente turno. Una ruta seleccionada se adjunta como `type: "mention"`. El panel permite analizar, configurar e instalar MCP y plugins con confirmación. Los MCP HTTPS se escriben en `.codex/config.toml` del proyecto confiable. App Server instala los plugins a nivel de Codex; Codex Suite guarda su evaluación, estado funcional y recomendaciones por workspace y muestra este alcance antes de confirmar. ## 10. Revisión, herramientas, cambios y aprobaciones `Revisar` usa `review/start`, con estos objetivos: - cambios sin commit; - rama base; - commit concreto; - instrucciones personalizadas. Los eventos de App Server llegan por Server-Sent Events: ```text App Server -> bridge -> /api/codex/events -> EventSource del navegador ``` La UI representa: - mensajes del usuario; - mensajes finales de Codex; - ejecuciones de comandos; - llamadas de herramientas; - cambios de archivos y diffs; - estado del turn; - aprobaciones pendientes. Se filtran eventos de razonamiento interno, respuestas raw y campos cifrados. Solo se muestran resultados públicos y resúmenes operativos. ## 11. Comandos `/` y equivalentes gráficos El panel `Control > Comandos /` incluye el catálogo completo consultado por el frontend. Hay tres clases: ### Integrado Existe un método de App Server o una operación web equivalente real. Ejemplos: | Comando | Equivalente web | |---|---| | `/new`, `/clear` | Nuevo thread | | `/resume` | Lista de threads | | `/fork` | Bifurcar | | `/compact` | Compactar | | `/rename` | Renombrar | | `/archive` | Archivar | | `/delete` | Eliminar con confirmación | | `/goal` | Objetivo persistente | | `/model` | Selector de modelo | | `/reasoning` | Selector de esfuerzo | | `/fast` | Selector de velocidad | | `/personality` | Selector de personalidad | | `/permissions` | Selector solo lectura/escritura | | `/review` | Revisión nativa | | `/skills` | Inventario y selección de skill | | `/mcp` | Estado MCP | | `/apps` | Apps anunciadas por Codex | | `/plugins` | Inventario de plugins | | `/hooks` | Inventario de hooks | | `/usage` | Uso y límites | | `/stop` | Cancelar turno | | `/copy` | Copiar última respuesta | ### Workflow No hay un método aislado equivalente, pero se prepara una petición segura y revisable para el agente. Ejemplos: - `/init`: crear o mejorar `AGENTS.md`; - `/debug-config`: diagnosticar configuración sin mostrar secretos; - `/import`: preparar una importación controlada; - `/memories`: convertir decisiones duraderas en documentación; - `/agent`: evaluar delegación solo cuando se solicita explícitamente. ### Propio del host Es una función de la CLI, el IDE o la aplicación de escritorio y no debe fingirse en una web. Ejemplos: - `/vim`, `/keymap`, `/raw`, `/statusline`, `/title`, `/theme`; - `/quit`, `/exit`; - `/cloud`, `/cloud-environment`; - `/worktree` cuando no existe un repositorio Git válido; - `/setup-default-sandbox`; - `/sandbox-add-read-dir`. El panel explica el equivalente o por qué no aplica. No envía estas cadenas como prompt esperando que el agente cambie una función del terminal. ## 12. Por qué puede resultar mejor que este chat La mejora no consiste en que el modelo sea distinto. Consiste en que Codex Suite está especializada en el bridge: - selector permanente de los workspaces del equipo; - historial local; - streaming de herramientas y cambios; - aprobaciones táctiles; - cancelación y steer; - revisión nativa; - recursos Codex visibles; - equivalentes gráficos para comandos; - acceso directo desde `/apps`; - funcionamiento desde móvil por Tailscale; - límites de archivos fijados por el servidor. La conversación general sigue siendo útil para consultas amplias. Codex Suite está optimizada para operar los proyectos locales del bridge. ## 13. Contexto histórico de validaciones anteriores ### “Vista móvil inicial forzada a chat” En móvil solo se muestra un panel cada vez: threads, chat o control. El HTML y JavaScript fijan `chat` como panel inicial para evitar que una recarga deje visible la lista lateral o dos pestañas marcadas a la vez. ### “Decodificador DevTools compatible con Blob, ArrayBuffer y vistas tipadas” El verificador automático controla Chrome mediante DevTools. Dependiendo de la versión de Node o Chrome, una respuesta WebSocket puede llegar como texto, `Blob`, bloque binario o vista de bytes. El decodificador convierte cualquiera de esos formatos a texto JSON antes de procesarlo. Esto pertenece a las pruebas. No afecta al protocolo entre el navegador y el bridge. ### “CDP estabilizado mediante sesión explícita” CDP significa Chrome DevTools Protocol. El verificador se conecta al endpoint del navegador, adjunta una sesión a la pestaña y aplica navegación, viewport y captura a esa sesión concreta. Los timeouts impiden que una prueba quede colgada si Chrome no responde. ### “npm test: 4/4” Ese mensaje correspondía a la primera validación, cuando había cuatro casos. La suite actual tiene veintiocho pruebas y amplía la cobertura a: - arranque de Codex en Windows sin `shell: true`; - límites del catálogo de workspaces; - sandbox y aprobaciones del turn; - filtrado de razonamiento privado. - modo de solo lectura sin escritura ni red; - sanitización del inventario de capacidades; - controles nativos de threads; - catálogo de comandos integrados, workflows y funciones propias del host. El número indica cobertura específica, no que todo el producto tenga únicamente cuatro casos posibles. El manual y la entrega deben acompañarse de smoke tests HTTP y capturas responsive. ### “Sin fallbacks ni credenciales incrustadas” Se buscaron tokens, claves con apariencia real, uso de `localStorage` para el token de Codex y lectura de token desde query string en la aplicación Codex. La UI no contiene un token de respaldo. ### “Capturas verificadas” El verificador abrió una sesión autenticada y capturó: - escritorio `1440 x 900`; - móvil `390 x 844`. También comprobó que no hubiera desbordamiento horizontal, que el login estuviera cerrado, que hubiera workspaces y que el compositor fuera visible. ### “Servidor de prueba 8101 y DevTools detenidos” El bridge de producción usa `8095`. Las pruebas levantaron temporalmente otra instancia en `8101` y Chrome expuso DevTools en puertos aislados. Al finalizar se cerraron para evitar procesos duplicados y puertos de depuración abiertos. El bridge principal de `8095` se dejó operativo. ## 14. Archivos principales | Archivo | Responsabilidad | |---|---| | `server.js` | Sesión, rutas REST/SSE y página Codex | | `lib/codex-app-server.js` | Cliente JSONL persistente de App Server | | `lib/codex-chat.js` | Workspaces, sandbox y operaciones Codex | | `lib/codex-command-catalog.js` | Catálogo de comandos y equivalentes | | `static/codex-suite/index.html` | Estructura de la aplicación | | `static/codex-suite/app.js` | Estado, streaming y acciones gráficas | | `static/codex-suite/style.css` | Diseño responsive | | `config/equipitello-apps.json` | Registro en `/apps` | | `config/app-docs.json` | Registro del manual | | `tools/verify-codex-ui.mjs` | Auditoría visual autenticada | ## 15. Puesta en marcha ```powershell cd C:\xampp\htdocs\cursor-mobile-bridge npm test .\cursor-bridge-manager.ps1 -Restart ``` Comprobaciones: ```powershell curl http://127.0.0.1:8095/health curl http://127.0.0.1:8095/apps curl http://127.0.0.1:8095/codex-suite ``` La API Codex debe devolver `401` sin sesión: ```powershell curl http://127.0.0.1:8095/api/codex/workspaces ``` ## 16. Diagnóstico | Síntoma | Comprobación | |---|---| | Codex Suite no aparece en `/apps` | Recarga sin caché y consulta `/api/launcher?fast=1` | | Token inválido | Verifica y rota `BRIDGE_TOKEN` | | No carga desde Tailscale | Revisa Tailscale en ambos dispositivos y firewall de `8095` | | No aparecen workspaces | Revisa `HTDOCS_ROOT` y `EXTRA_PROJECT_PATHS` | | App Server no arranca | Comprueba `codex --version` y el shim npm de Windows | | Turn bloqueado | La Suite reconcilia automáticamente el estado; revisa Control > Eventos y aprobaciones, y usa Cancelar si App Server confirma que sigue activo | | Skill no aparece | Revisa su `SKILL.md` y pulsa recarga del workspace | | Review falla | El objetivo puede requerir un repositorio Git válido | | No hay modelos o uso | Revisa autenticación local de Codex y el panel Recursos | ### Recuperación de compactaciones y turns interrumpidos El bridge registra en backend cada turn activo, su fase y la hora del último evento. Tras una reconexión SSE y durante silencios prolongados, el frontend consulta ese registro. Si App Server terminó, se reinició o ya no reconoce el turn, Codex Suite recarga el historial disponible y desbloquea el compositor. Si el turn continúa realmente activo pero no emite eventos durante tres minutos, muestra una advertencia y conserva la cancelación segura, sin inventar una respuesta terminal. La misma vigilancia cubre herramientas largas, aprobaciones, pérdida del stream y cierre inesperado del proceso. Las aprobaciones pendientes permanecen visibles como espera explícita y no se tratan como un bloqueo. ### Varias ventanas, PWA y proyectos en paralelo Cerrar Chrome o la PWA no cancela un turn: la ejecución pertenece al backend y a Codex App Server, no a la pestaña. Al volver a primer plano, la Suite reconecta SSE y reconcilia conversaciones, runtime, aprobaciones, checkpoints y cambios. Esto funciona mientras el bridge de Windows siga ejecutándose; apagar el PC, detener el bridge o finalizar App Server puede interrumpir el turn, aunque el historial ya persistido se conserva. Los eventos incluyen identidad de thread y el cliente descarta del chat visible los eventos de otros threads. Las conversaciones activas se señalan en la lista y puede cambiarse de workspace mientras continúan. Varias PWA/ventanas reciben el mismo stream del servidor. La concurrencia no es ilimitada: depende de CPU, memoria, límites del proveedor/modelo y herramientas utilizadas. Al cargar Codex Suite no se selecciona ningún workspace. Esta decisión evita abrir accidentalmente el último proyecto utilizado. El administrador elige explícitamente el proyecto antes de crear o reanudar una conversación. ### Actualizaciones de la PWA Al instalar o volver a primer plano, la aplicación solicita al navegador comprobar el service worker sin reutilizar su caché HTTP. Cuando existe una nueva versión del shell, la activa y recarga una vez de forma controlada. La versión actual es `codex-suite-shell-v15`. En iPhone la PWA usa WebKit aunque se haya añadido desde Chrome; el sistema puede suspender JavaScript en segundo plano, pero el backend continúa y el estado se recupera al regresar. ### Misiones y Evidence Ledger La pestaña **Control → Misiones** reúne los turnos ejecutados en el proyecto activo. El resumen muestra misiones, evidencias, tareas activas, aprobaciones pendientes e incidencias. Se puede limitar la vista a la conversación actual y abrir una misión para consultar su secuencia y los archivos relativos implicados. El ledger es deliberadamente redactado: persiste identificadores, fechas, categorías, estados, decisiones de aprobación y rutas relativas. No guarda prompts, respuestas completas, razonamiento privado, comandos, salidas, diffs ni credenciales. Cada proyecto mantiene su propio archivo JSONL y el frontend solo dispone de lectura autenticada. Esta primera versión no ofrece todavía replay, exportación ni copia cifrada. ### Router de modelos FCC **Control → Modelos** consulta el servicio local FCC en `127.0.0.1:8082`. Codex Suite filtra el catálogo para retirar embeddings, OCR, audio, imagen, moderación y otros modelos que no sirven como agente de ingeniería. El filtro inicial enseña modelos locales o declarados gratuitos; **Todos** añade proveedores cuyo coste no está verificado. La etiqueta de coste es informativa: `local` significa ejecución en LM Studio/Ollama/llama.cpp; `gratis` solo significa que el identificador o FCC lo declara así. Límites, privacidad, disponibilidad y tarifas dependen del proveedor. La puntuación es heurística y no afirma que un modelo sea mejor que Codex. La referencia oficial resuelta en este corte es `gpt-5.6-sol`; un identificador homónimo servido por un tercero no demuestra que sea el mismo endpoint, versión o nivel de servicio. Al pulsar **Usar en conversaciones nuevas**, el backend registra `fcc_local` como proveedor Responses de Codex y usa una credencial cargada exclusivamente en el proceso servidor desde `.fcc`; nunca se devuelve al HTML o JavaScript. Se exige confirmación explícita y hay que abrir una conversación nueva. Si un turno falla, la interfaz ofrece acudir al panel de modelos. No existe una API fiable para conocer cuándo se repone una cuota de Codex/OpenAI, por lo que no se inventa una fecha: la disponibilidad se comprueba al volver a abrir o actualizar el panel. **Comprobar catálogos** confirma que el proveedor permite listar modelos; no demuestra inferencia. **Probar inferencia** ejecuta una respuesta mínima y streaming en un modelo representativo por proveedor, con confirmación previa porque puede consumir cuota. El resultado persistido contiene solo proveedor, modelo, estado, latencia, tamaño, HTTP, tipo de error y fecha. Nunca almacena prompts, respuestas ni claves. Un modelo solo debe participar en selección automática después de superar inferencia y, posteriormente, los evals específicos del workspace. La activación está cerrada por defecto: el botón permanece deshabilitado hasta que ese identificador exacto haya producido texto en una inferencia real. Que otro modelo del mismo proveedor funcione no habilita el resto del catálogo. ### Revisión posterior por archivo Al finalizar un turn con cambios revisables, el checkpoint muestra cada ruta, su diff y acciones independientes **Aceptar archivo** y **Rechazar archivo**, además de las acciones globales. Aceptar un archivo no obliga a aceptar los restantes. Si el despliegue al aceptar está habilitado, solo se envían los archivos aceptados. Archivos binarios o superiores al límite de snapshot pueden no disponer de diff textual. ### Límites de conversaciones y workspaces compuestos Una conversación de este mismo Codex App Server puede reabrirse desde la Suite. El listado filtra por espacio de trabajo usando el `cwd` del rollout en disco y un índice durable `storage/codex-thread-index.json` (sobrevive a reinicios del bridge). Un chat mantenido en otro producto, servicio o sesión que no comparta el mismo almacén de threads no se sincroniza bidireccionalmente de forma automática; los chats del IDE Cursor se listan aparte vía el motor Cursor cuando la API key tiene entitlement. Los espacios del selector se descubren automáticamente desde carpetas bajo `HTDOCS_ROOT` (p. ej. `C:\xampp\htdocs`), `CURSOR_PROJECTS_DIR`, `EXTRA_PROJECT_PATHS` y el allowlist durable `storage/codex-workspace-allowlist.json`. Desde el selector de la Suite puedes: - **Nueva área** — crea un proyecto bajo una raíz allowlist (plantillas `empty`, `php`, `php-web`, `node`, `static`) sin `.vscode` por defecto. - **Vincular carpeta** — añade una carpeta existente solo si está bajo las raíces allowlist; no borra nada al desvincular. Al elegir un área se cargan explorador, perfil (señales IDE: `AGENTS.md`, `.cursor/rules`, slug Cursor, Serena) y el listado local de chats Cursor. El motor Cursor muestra historial local (`agent-transcripts` + SDK); no incluye chats solo en la nube. Durante un turno Cursor, tools y cambios de archivo aparecen en vivo en la línea de tiempo móvil. Las áreas permiten agrupar carpetas dentro de una única raíz autorizada. Todavía no unen carpetas arbitrarias de proyectos distintos en un sandbox compuesto. Un workspace multi-raíz requerirá consentimiento explícito por raíz, políticas de escritura independientes y revisión de escapes; no debe simularse rebajando el aislamiento actual. ## 17. Política de mantenimiento - No exponer App Server directamente a Tailscale. - No añadir tokens a URLs o JavaScript. - No se admite el acceso heredado `/codex-suite?token=…`; el login usa exclusivamente `POST /api/codex/session` y cookie `HttpOnly`. - No ampliar raíces de workspace desde la UI. - No habilitar red sin una decisión de seguridad explícita. - Mantener métodos App Server alineados con el esquema generado por la versión instalada. - Probar `/apps`, `/codex-suite`, sesión, capacidades, threads, SSE y ambos breakpoints tras cada actualización importante. ## 18. Referencias oficiales de Codex La implementación se contrastó con la documentación y el esquema generado por la versión instalada de Codex App Server: - Manual y protocolo App Server: `https://developers.openai.com/codex/codex-manual` - Comandos de Codex CLI: `https://learn.chatgpt.com/docs/developer-commands?surface=cli` - Comandos de la extensión IDE: `https://learn.chatgpt.com/docs/developer-commands?surface=ide` Las funciones del terminal o del IDE pueden no tener un método App Server equivalente. Codex Suite las clasifica como función del host en vez de simularlas mediante prompts. ## 19. Último resultado de verificación consolidado Verificación ejecutada el **22 de julio de 2026, 23:07 (Europe/Madrid, UTC+02:00)**. El estado vigente posterior se resume en `CODEX-SUITE-STATUS.md`: - `npm test`: 28 pruebas superadas; - Codex CLI detectado: `0.144.6`; - App Server real iniciado por `stdio`: 7 modelos y 1 raíz de skills anunciados; - `/health`, `/apps` y `/codex-suite`: HTTP 200 en el bridge `8095`; - `/api/codex/workspaces` sin sesión: HTTP 401; - cookie de sesión: `HttpOnly` y `SameSite=Strict`; - sesión autenticada, administración, diagnóstico y checkpoints: HTTP 200; - service worker registrado con scope `/codex-suite` y manifest detectado; - inicio sin workspace seleccionado y compositor bloqueado hasta elección explícita; - aislamiento de eventos concurrentes: un evento de otro thread no altera el chat visible; - manual integrado abierto en `/apps/docs?app=codex-suite`; - launcher: 47 accesos y URL Tailscale de Codex Suite generada; - inventario de capacidades: HTTP 200 sin rutas físicas ni campos secretos; - escritorio `1440 × 900`: chat activo, sin overflow y compositor visible; - móvil `390 × 844`: chat activo, sin overflow, compositor compacto y opciones avanzadas desplegables; - modos Consultar/Planificar verificados con permiso `readOnly` y retorno de Plan a Agente; - instrucciones de Autopilot, `#codebase` y acciones inteligentes verificadas en navegador; - shell standalone, teclado virtual y navegación inferior verificados; - Explorador: 60 entradas verificadas, drag & drop, contexto por click y preview en ambos breakpoints; - Catálogo público: 60 fichas MCP recuperadas; 7 complementos nativos y recomendaciones calculadas por cada proyecto; - Centro de pruebas: 17 comprobaciones, 15 correctas, 2 avisos operativos y 0 errores; - `npm audit --omit=dev`: 0 vulnerabilidades conocidas; - puertos temporales `8101`, `9331` y `9332`: cerrados después de la prueba. Capturas: - `storage/codex-suite-desktop.png` - `storage/codex-suite-mobile.png` - `storage/codex-suite-integrations-desktop.png` - `storage/codex-suite-integrations-mobile.png` - `storage/codex-suite-security-desktop.png` - `storage/codex-suite-security-mobile.png` - `storage/codex-suite-explorer-desktop.png` - `storage/codex-suite-explorer-mobile.png` - `storage/codex-suite-complements.png` ## 20. Adjuntar contexto, archivos e imágenes El botón `＋` del compositor permite seleccionar hasta 10 archivos por envío. Cada archivo: - tiene un límite de 5 MB; - se guarda dentro del workspace seleccionado, en `.codex-suite/attachments`; - nunca se identifica ante el navegador mediante una ruta absoluta; - aparece como chip removible antes de enviar; - se envía a App Server como `localImage` si es PNG, JPEG, WebP o GIF; - se envía como `mention` para el resto de archivos admitidos. Las extensiones ejecutables (`.exe`, `.dll`, `.cmd`, `.bat`, `.ps1`, `.msi`, entre otras) se rechazan. Adjuntar una imagen permite que el modelo analice capturas, diagramas y errores visuales; conviene acompañarla con una pregunta concreta. La acción **Adjuntar ruta** del panel Control añade un archivo que ya existe dentro del workspace. El backend resuelve la ruta, comprueba que no salga de la raíz permitida y solo entonces la entrega a App Server. ## 21. Ajustes del producto y administración de Codex La pestaña **Ajustes** contiene tres capas diferentes: 1. Apariencia de Codex Suite: nombre, bienvenida, tema completo, acento, densidad, tamaño y movimiento. 2. Comportamiento del cliente y bridge: envío con Enter, panel Control, eventos, threads y permiso predeterminado. 3. Configuración del runtime Codex: proveedor, modelo, esfuerzo, tier, personalidad, almacenamiento de credenciales, aprobación, revisor y sandbox. Los temas completos disponibles son Sistema, Luz limpia, Grafito, Medianoche y Papel cálido. Medianoche y Papel cálido cambian canvas, superficies, texto, bordes, código y sombras; no son únicamente cambios de color de acento. ### API key La API key se administra como secreto de solo escritura: - el frontend puede reemplazarla o eliminarla; - `GET /api/codex/admin` devuelve únicamente `configured: true/false`; - ningún endpoint devuelve el valor; - no se incluye en HTML, logs, URLs o capturas; - el cambio recomienda reiniciar App Server para garantizar que todos los procesos recarguen la credencial. El archivo de credenciales puede ser `auth.json` o el almacén seguro del sistema según `cli_auth_credentials_store`. La documentación oficial recomienda tratar `auth.json` como una contraseña. Para una instalación compartida es preferible `keyring`. ### config.toml Codex Suite usa los métodos nativos `config/read` y `config/batchWrite` de App Server. No reescribe TOML mediante búsquedas o reemplazos. El panel solo muestra y modifica una lista cerrada de campos públicos; preserva las demás tablas y no devuelve rutas de proyectos, cabeceras o secretos. En Codex CLI 0.144.6 las claves `disable_response_storage` y `preferred_auth_method` del archivo existente no aparecen en el esquema efectivo. El panel las señala como antiguas/no gestionadas y no afirma que tengan efecto. Debe usarse `--strict-config` en comandos compatibles al actualizar Codex para detectar claves retiradas. El aviso del panel se refiere a **dos parámetros TOML heredados**, no a dos API keys. Codex Suite no enumera, conserva ni revela versiones anteriores de una API key. ## 22. Centro de pruebas La pestaña **Test** ejecuta comprobaciones no destructivas de: - sesión del bridge; - configuración persistente de Codex Suite; - presencia de credencial, sin leerla; - workspace autorizado; - conexión con Codex App Server; - lectura segura de `config.toml`; - catálogo de modelos; - skills y servidores MCP; - soporte de adjuntos `localImage` y `mention`; - políticas de red, workspace y aprobaciones. Cada resultado se clasifica como correcto, aviso o error y muestra la duración total. El Centro de pruebas no ejecuta herramientas, no escribe en el workspace y no realiza una llamada facturable al modelo. La auditoría adicional `tools/verify-codex-ui.mjs` abre Chrome en escritorio y móvil, comprueba overflow, panel desplazable, controles táctiles, compositor compacto/expandido, standalone, teclado, modos agénticos, permisos read-only, acciones inteligentes, formulario de ajustes y captura ambos breakpoints. El diagnóstico también incluye el check **Contratos de persistencia Codex** cuando el facade 0.3 está activo. La auditoría read-only completa está en `GET /api/codex/persistence/audit` y en CLI: ```powershell node tools/audit-codex-persistence.mjs ``` No reescribe datos por defecto. La opción `--quarantine` solo aísla JSON irrecuperable renombrándolo a `.corrupt.`. El sellado `schemaVersion` ocurre al volver a escribir cada store. El selector de motor admite **Codex App Server** (canónico para Evidence OS) y **Cursor SDK** (`CURSOR_API_KEY`) con potencial completo del bridge: continuar sesión Suite, reanudar agentes SDK, enlazar chats del IDE (`agent-transcripts`) e opcionalmente **Serena MCP**. En Opciones del compositor aparecen el selector de chat Cursor y el toggle Serena. Un chat **nuevo Suite** (opción por defecto del picker) fuerza `newChat` y crea un JSONL UUID bajo el slug del workspace; el binding durable (`storage/codex-conversation-bindings.json`) guarda `agentId` + `transcriptPath`. Tras cada turno con texto, Suite hace append enriquecido (`suite_turn`) al JSONL. **Para verlo en el IDE**: `Desarrollador: Recargar ventana` o reabrir el chat (no hay sync en caliente del panel Composer). Cursor no sustituye checkpoints ni el ledger de Codex; etiqueta su ejecución como `provider: cursor-sdk`. APIs: `GET /api/codex/cursor/sources`, `GET /api/codex/cursor/transcript`, `POST .../cursor-turns`. Índice **Privado / Composer** (Control → Sistema, solo con `CODEX_COMPOSER_PRIVATE=1`): `GET /api/codex/private/composer-index` lee metadatos de `composer.composerHeaders` en `state.vscdb` **sin escribir**. Chats Composer sin JSONL no son ejecutables desde Suite. Si aparece **“upgrade to Pro” / plan_required** con el IDE en Pro: la `CURSOR_API_KEY` del `.env` está clasificada como Free en `api.cursor.com` (suele ser otra cuenta o una clave antigua). Regenera la clave en [cursor.com/dashboard/api](https://cursor.com/dashboard/api) con la misma cuenta Pro, actualiza `.env` y reinicia el bridge. Control/status expone `entitlement` para diagnosticarlo. ## 23. Incidencia de mensajes duplicados El cliente crea un mensaje optimista para que el envío aparezca inmediatamente. App Server confirma después el mismo mensaje con un ID definitivo. Antes se conservaban ambos IDs y se mostraban dos líneas. La corrección mantiene una cola de mensajes locales pendientes y sustituye el primero por el elemento confirmado; los eventos `item/started` y `item/completed` posteriores actualizan el mismo ID. ## 24. Evolución comercial futura (solo documentación) No se ha implementado monetización, multi-tenant ni facturación. Para una evolución comercial segura se recomienda separar estas fases: 1. Identidad y tenants: usuarios, organizaciones, roles, sesiones revocables y auditoría por actor. 2. Aislamiento: workspaces por tenant, credenciales en un vault, cuotas y procesos App Server aislados. 3. Observabilidad: métricas de latencia, errores, uso, aprobaciones y salud sin registrar prompts o secretos por defecto. 4. Producto: onboarding, plantillas de workspace, políticas administradas, perfiles y exportación de actividad. 5. Operación: migraciones versionadas, backups, recuperación, límites de carga, colas y actualizaciones compatibles. 6. Negocio: planes, medición de consumo, facturación, términos, privacidad, soporte y borrado de datos. Antes de comercializar debe sustituirse la sesión global en memoria por identidad multiusuario, mover credenciales a un gestor de secretos y diseñar aislamiento por tenant. La arquitectura actual sigue siendo deliberadamente single-host y no debe presentarse como SaaS multiusuario. ## 25. Retomar una conversación de Codex Los threads pertenecen a Codex App Server y son persistentes. Al elegir el mismo workspace, la columna **Threads** carga su historial; al abrir uno, Codex Suite llama a `thread/resume` y puede continuar el contexto desde el frontend. Se verificó específicamente que el workspace `cursor-mobile-bridge` contiene el thread iniciado con la petición «Trabaja únicamente en este proyecto…». Esta conversación puede abrirse y continuarse desde Codex Suite. Un chat de otro producto que no esté persistido por el mismo entorno Codex no se importa automáticamente. ## 26. Cambios, diffs y aprobación Cuando App Server solicita aprobación para `item/fileChange/requestApproval` o `applyPatchApproval`, Codex Suite presenta la lista de archivos y un diff coloreado. El administrador puede aprobar, rechazar o cancelar. Los comandos sensibles siguen el mismo flujo y nunca se ejecutan desde JavaScript del navegador. Además, al terminar cada turn que haya modificado archivos aparece **Revisar cambios de Codex**, inspirado en GitHub Copilot Chat para VS Code. El panel incluye: - diff estable anterior/posterior por archivo; - estado Nuevo, Modificado o Eliminado; - **Aceptar archivo** y **Rechazar archivo**; - **Aceptar todo** y **Rechazar todo**; - diseño desplegable y desplazable en escritorio y móvil. Aceptar conserva el archivo tal como lo dejó Codex. Rechazar restaura únicamente ese archivo a su contenido anterior al turn. Antes de restaurarlo, el backend compara su hash con el resultado original; si otra persona o proceso lo editó después, devuelve conflicto `409` y no sobrescribe la versión más nueva. En un rechazo múltiple se validan todos los archivos antes de escribir y se revierte la operación si falla una restauración. La revisión se ejecuta en el backend y el navegador nunca escribe archivos directamente. En modo **Solo lectura** no se permiten escrituras. En **Escritura en workspace** Codex opera dentro de la raíz seleccionada y solicita aprobación previa conforme a `on-request`; la revisión posterior por archivo es una capa independiente que aparece al finalizar. La captura del estado anterior y posterior está disponible para archivos de hasta 512 KB. Los archivos binarios admiten aceptar/rechazar, aunque el panel no intenta renderizar su contenido. Los archivos superiores al límite se excluyen de esta revisión para evitar almacenar copias excesivas y nunca se interpretan erróneamente como creados o eliminados. Los snapshots se guardan únicamente en el backend, dentro de `storage/codex-checkpoints`, y esa carpeta está excluida mediante `.gitignore` porque puede contener fragmentos del código del workspace. La API pública de listado no devuelve los contenidos base64 internos; el endpoint de revisión entrega únicamente rutas relativas, estado y diff al administrador autenticado. ## 27. Checkpoints y rollback Antes de cada turn nuevo, el backend captura el estado de los archivos pequeños del workspace. Cuando el turn termina, persiste un checkpoint incremental con los archivos creados, modificados o eliminados. La acción **Volver a un punto**: 1. exige seleccionar y confirmar el identificador exacto del checkpoint; 2. recorta mediante App Server el turn objetivo y los posteriores; 3. restaura los archivos afectados en orden inverso; 4. elimina los checkpoints que ya no pertenecen al historial activo. Limitaciones importantes: - el rollback real de archivos solo existe para turns ejecutados después de instalar esta versión; - los threads históricos pueden reanudarse, pero no tienen snapshots retroactivos; - se conservan hasta 30 checkpoints por thread; - archivos individuales mayores de 512 KB, repositorios Git, dependencias, builds y almacenamiento interno no se incluyen; - un cambio externo realizado al mismo tiempo que un turn puede quedar incluido en su checkpoint; - no debe usarse como sustituto de commits o copias de seguridad para trabajo crítico. ## 28. Modelo Auto La opción **Auto · predeterminado** envía `model: null`. De ese modo App Server y el proveedor usan el modelo predeterminado efectivo de `config.toml` o de su configuración. No es un clasificador propio que cambie de modelo semánticamente en mitad de una conversación, y la interfaz no afirma esa capacidad. Para fijar un modelo concreto, selecciónalo en el compositor; el esfuerzo y tier se adaptan a las capacidades anunciadas por ese modelo. ## 29. Manual integrado y PWA para iPhone El botón `?` abre este manual dentro de Codex Suite, con índice y búsqueda. El contenido procede de este Markdown, por lo que cada entrega debe actualizar el archivo y el manual integrado reflejará los cambios sin duplicar documentación en HTML. Para instalarlo en iPhone: 1. conecta Tailscale y abre Codex Suite en Safari; 2. pulsa **Compartir**; 3. elige **Añadir a pantalla de inicio**; 4. inicia Codex Suite desde su icono. La interfaz usa `viewport-fit=cover`, `visualViewport`, áreas seguras, altura dinámica, controles táctiles de al menos 48 px, navegación inferior y modo standalone. Al abrir el teclado, la navegación inferior desaparece y el panel se recalcula con la altura visual disponible. El service worker almacena únicamente el shell estático y excluye todas las rutas `/api`; el chat siempre necesita el bridge. Safari solo habilita service workers en un contexto seguro (HTTPS, salvo localhost). Con el acceso Tailscale actual por HTTP, la app de inicio conserva el aspecto standalone pero no debe prometer caché offline; para disponer de service worker en el iPhone debe publicarse el bridge mediante HTTPS confiable. ## 30. Alcance del panel administrador La instancia actual es un panel de administrador single-host. Por eso muestra configuración operativa, proveedores, capacidades, diagnósticos, eventos, diffs y rutas relativas necesarias para decidir. Aun siendo un único administrador, secretos como API keys, cookies y tokens continúan siendo write-only: una inyección de script, captura o log no debe poder recuperarlos desde el frontend. La prioridad premium documentada para próximas iteraciones es: historial de checkpoints más visual, comparación consolidada por turn, perfiles de configuración, exportación de diagnósticos saneados, métricas locales de latencia/uso y un onboarding de seguridad. Multiusuario, facturación y comercialización permanecen fuera de implementación por ahora. ## 31. Modos agénticos, especialistas y acciones inteligentes El compositor ofrece cuatro workflows: | Modo | Comportamiento | Escritura | |---|---|---:| | Agente | Inspecciona, implementa y verifica | Según selector de permisos | | Consultar | Explica y analiza | Forzada a solo lectura | | Planificar | Investiga y entrega un plan verificable | Forzada a solo lectura | | Autopilot | Implementa end-to-end, prueba y autocorrige | Según selector y aprobaciones | Los participantes `@workspace`, `@tester`, `@reviewer`, `@terminal` y `@browser` no son identidades remotas independientes: son perfiles operativos que enfocan el siguiente turn. `@browser` solo puede usar Browser Use, búsqueda o un MCP de navegador cuando App Server anuncie esa herramienta y la política la autorice. El bridge no habilita red libre al shell. La delegación permite un agente, subagentes únicamente cuando el texto los pida o una solicitud explícita de subagentes proactivos. La actividad de subagentes anunciada por App Server se muestra en el timeline. El navegador nunca crea procesos directamente. El menú de adjuntos añade `#codebase` y `#terminal`. El primero solicita una exploración amplia dentro del workspace; el segundo prioriza salidas y errores ya presentes en el thread. No existe todavía un índice semántico remoto Enterprise propio: la recuperación real depende de las herramientas y contexto de App Server. Las acciones **Explicar**, **Corregir**, **Crear tests**, **Revisar** y **Commit** preparan prompts operativos editables. Commit genera el mensaje, pero no ejecuta `git commit` sin una petición y las aprobaciones correspondientes. ## 32. Instrucciones persistentes del workspace `Control > Ajustes > AGENTS.md` permite leer y editar el archivo de instrucciones de la raíz del workspace. El guardado requiere la confirmación `SAVE_AGENTS`, está limitado a 200 KB y no admite elegir otra ruta. Codex usa `AGENTS.md` como superficie nativa de instrucciones persistentes; no se simula `.github/copilot-instructions.md`. Las instrucciones pueden definir convenciones, comandos de prueba, arquitectura y límites de propiedad. No deben contener API keys, tokens ni contraseñas. ## 33. Matriz honesta de equivalencia con Copilot Chat | Capacidad solicitada | Estado en Codex Suite | |---|---| | Agent, Ask, Plan y Autopilot | Integrado con permisos y prompts verificables | | Pruebas y autocorrección | Autopilot lo solicita; ejecución real por herramientas de App Server | | Navegación web/local | Condicionada a Browser Use, búsqueda o MCP disponible y autorizado | | Subagentes | Solicitud explícita y visualización de actividad soportadas | | MCP, skills, plugins y hooks | Inventario nativo de App Server; administración global no expuesta | | `#codebase`, `#terminal` | Contexto operativo integrado | | Participantes `@` | Perfiles especializados integrados | | Modelos | Catálogo dinámico de App Server y opción Auto efectiva | | Instrucciones persistentes | CRUD seguro de `AGENTS.md` en la raíz | | Sesiones paralelas y memoria | Threads persistentes, bifurcación, objetivos y compactación | | Smart actions | Cinco acciones editables de un clic | | Cambios por archivo | Diff, aceptar/rechazar, conflicto por hash y rollback | No se afirma paridad con indexación semántica Enterprise remota, agentes centralizados multi-tenant ni catálogo multi-proveedor ajeno a App Server. Esas funciones requieren arquitectura adicional y permanecen documentadas como evolución futura, no como capacidades simuladas. ## 34. Explorador de archivos del proyecto La columna izquierda dispone de **Threads** y **Explorador**. El árbol se carga de forma incremental desde el backend: - solo resuelve rutas dentro del workspace autorizado; - omite enlaces simbólicos y carpetas pesadas como `.git`, `node_modules`, `vendor`, `dist` y `build`; - ordena primero carpetas y después archivos; - no devuelve rutas absolutas; - permite expandir carpetas sin descargar todo el proyecto; - abre archivos de texto de hasta 256 KB en una vista previa de solo lectura; - dispone de scroll independiente en escritorio y móvil. Pulsar `#` junto a un elemento lo añade al siguiente turn. En escritorio también se puede arrastrar el archivo o carpeta hasta el compositor. El botón `#` es la alternativa táctil para iPhone, donde drag & drop puede depender de la versión del sistema. **Nueva carpeta** permite crear una carpeta dentro del proyecto. Requiere `CREATE_FOLDER`, comprueba que la carpeta padre exista y rechaza rutas absolutas, `..`, junctions o escapes fuera del workspace. No permite añadir desde el navegador una raíz arbitraria del disco: las raíces continúan gobernadas por `HTDOCS_ROOT` y `EXTRA_PROJECT_PATHS`. ## 35. Áreas de trabajo, memoria e instrucciones `Control > Workspace` crea áreas comparables a una vista multi-carpeta de VS Code, pero confinadas a un único proyecto seguro. Cada área contiene: - nombre; - carpetas relativas del proyecto; - instrucciones específicas; - memoria específica. La memoria general y las áreas se guardan en `.codex-suite/workspace-profile.json`. El directorio está excluido de checkpoints de código y no debe contener contraseñas. Al iniciar un turn, el backend añade la memoria general, la memoria/instrucciones del área elegida y las carpetas del área como menciones nativas. `AGENTS.md` sigue siendo la fuente oficial de reglas duraderas que Codex descubre por jerarquía. La memoria de Codex Suite sirve para decisiones, estado operativo y contexto de negocio del proyecto; no sustituye convenciones compartidas que deban versionarse en `AGENTS.md`. Una área no une sandboxes de proyectos diferentes. Para trabajar con otro proyecto se cambia el workspace. Esta separación evita que una tarea autorizada para un proyecto obtenga escritura accidental en otro. ## 36. Herramientas y contexto desde la interfaz `Control > Recursos` permite: - elegir un modelo anunciado por App Server; - adjuntar una skill al siguiente turn; - seleccionar las herramientas de un servidor MCP como preferidas; - instalar un plugin disponible; - consultar apps, hooks y límites. Seleccionar una herramienta crea un chip `Tool:`. El backend la incorpora como preferencia, pero solo se ejecutará si App Server la anuncia, el modelo decide usarla y las políticas la autorizan. El navegador nunca invoca directamente el comando o la herramienta. Los archivos arrastrados, pulsados o buscados se envían como entradas `mention`; las imágenes subidas se envían como `localImage`. Todo se vuelve a validar en el backend aunque proceda del árbol mostrado por la propia aplicación. ## 37. Catálogo MCP y plugins `Control > Catálogo` combina dos fuentes diferentes: 1. **mcp.so** (`remote-servers` por defecto), usado como directorio público para descubrir servidores MCP remotos; 2. **marketplaces nativos de Codex**, incluido el catálogo curado que App Server tenga habilitado. **Analizar y configurar** abre una ficha real. Si el proveedor publica un endpoint HTTPS en la página, el backend lo extrae y lo rellena (nunca inventa URLs ni usa la página de mcp.so como endpoint). La ficha presenta en español finalidad, categoría, transporte, requisitos, coste verificado o desconocido, riesgo, puntuación de encaje y casos de uso. La evaluación se guarda en `.codex-suite/integrations.json` del workspace y nunca contiene contraseñas, tokens o claves. Consultar una ficha de mcp.so nunca ejecuta su snippet. Para instalar un MCP remoto hay que indicar un nombre y el endpoint HTTPS publicado por el proveedor, sin usuario, contraseña ni fragmentos en la URL, y confirmar `INSTALL_MCP:nombre`. El bridge escribe el servidor en `.codex/config.toml` del proyecto (App Server solo permite mutar el config de usuario; no se usa `filePath` de proyecto). Rechaza hosts `mcp.so`. Si el directorio no publica un endpoint (p. ej. solo stdio), la interfaz lo explica y permite pegarlo en Instalación avanzada solo si el proveedor lo documenta. Los plugins se inspeccionan con `plugin/read` y se instalan con `plugin/install`. Con autenticación por **API key**, el catálogo remoto curado de OpenAI puede exigir ChatGPT: en ese caso la API responde 409 con mensaje claro y, si el plugin ya está en caché local, se puede habilitar en el `config.toml` de usuario. Añadir un catálogo Git usa `marketplace/add` y requiere confirmación exacta. ## 38. Complementos nativos por workspace `Control > Complementos` escanea archivos representativos hasta una profundidad limitada y detecta stacks como PHP, JavaScript/TypeScript, HTML, CSS y MySQL/SQL. Ya no instala ni recomienda extensiones para VS Code. El catálogo contiene capacidades nativas de Codex Suite: calidad PHP, calidad JavaScript/TypeScript, experiencia web, seguridad SQL, despliegue aceptado, guardián de secretos y puertas de pruebas. Cada complemento muestra puntuación, motivos, requisitos, riesgo y coste. Al habilitarlo se guarda en el registro del workspace y su propósito entra en el contexto duradero de los siguientes turnos. Esto permite que Codex proponga usarlo cuando sea pertinente sin ejecutar automáticamente herramientas no anunciadas ni eludir aprobaciones. ## 39. Deploy FTP/SFTP ligado a la revisión El complemento **Deploy de archivos aceptados** soporta FTP, FTPS y SFTP. La configuración incluye host, puerto, usuario, ruta remota, reglas de ignore, subida al aceptar y sincronización opcional de borrados. Flujo: ```text Codex termina el turn -> checkpoint y diff por archivo -> administrador acepta uno o varios archivos -> el backend conserva solo los aceptados -> se suben únicamente esas rutas -> el resultado se registra en la memoria operativa del proyecto ``` Rechazar un archivo lo restaura y nunca lo añade al deploy. Aceptar varios sube únicamente los que estaban pendientes en esa decisión. Un fallo remoto no revierte la aceptación local: queda registrado como fallo para que el siguiente turn y el administrador puedan reintentarlo conscientemente. Las contraseñas nuevas no se escriben en `.vscode/sftp.json`, ni se devuelven al frontend. Se cifran mediante Windows DPAPI para la cuenta que ejecuta el bridge y se guardan fuera del workspace, en `storage/codex-deployments/`, excluido de Git. La UI solo recibe `hasPassword`. Cambiar de usuario Windows o mover el archivo cifrado a otro PC invalida la credencial. FTP transmite credenciales y contenido sin cifrar. Debe preferirse SFTP o FTPS. Se bloquean siempre `.env`, claves privadas, credenciales, `.git`, `.vscode`, `.codex-suite` y `node_modules`, además de las reglas configuradas. Sincronizar borrados está desactivado por defecto porque elimina archivos remotos. La configuración heredada `.vscode/sftp.json` de otras aplicaciones del bridge sigue operativa para ellas, pero Codex Suite utiliza su almacén protegido y no extrae automáticamente contraseñas en texto plano. ## 40. Estudio premium y siguiente evolución Prioridad recomendada, en este orden: 1. **Índice semántico incremental**: embeddings locales por workspace, invalidación por hash, referencias cruzadas y exclusión de secretos. Mejoraría `#codebase` sin enviar el repositorio entero. 2. **Editor web Monaco con Language Server Protocol**: previsualización editable, diagnósticos PHP/TS/CSS/SQL y navegación a símbolos. Debe ejecutarse en workers/procesos aislados, no cargar VSIX arbitrarios. 3. **Cola de despliegues transaccional**: reintentos, dry-run, comparación remoto/local, historial, rollback remoto y entornos staging/producción con promociones. 4. **Vault profesional**: Windows Credential Manager/Azure Key Vault/HashiCorp Vault, rotación, expiración, auditoría y credenciales por entorno. 5. **Políticas administradas**: allowlists de MCP/plugins/comandos, firma de plugins, SBOM, análisis de dependencias y aprobación separada para red, producción y borrados. 6. **Observabilidad privada**: latencia de turns/herramientas, tasa de éxito, coste, fallos de tests y despliegues; prompts y secretos excluidos por defecto. 7. **Automatizaciones y CI**: pipelines visuales reutilizables, gates de pruebas/seguridad, environments y hooks antes de aceptar o desplegar. 8. **Colaboración multiusuario**: identidad, roles, bloqueo optimista de archivos, comentarios sobre diffs y auditoría por actor. Requiere aislar sesiones App Server y credenciales por tenant. 9. **Evals de agentes**: conjuntos de tareas reales por proyecto, métricas de regresión, comparación de modelos y selección Auto basada en evidencia. 10. **Recuperación y continuidad**: copias cifradas de perfiles/checkpoints, exportación de threads, restauración verificable y política de retención. Para aspirar a un producto premium no conviene medir potencia solo por número de herramientas. Los diferenciadores defensibles son contexto correcto, ejecución verificable, seguridad de producción, revisión comprensible, memoria controlable y capacidad de recuperar cualquier cambio. Monetización, multi-tenant y facturación continúan fuera del código actual. ## 41. Centro de Seguridad y monitorización `Control > Seguridad` consolida información de solo lectura: - perfiles de Firewall de Windows; - estado de Microsoft Defender y BitLocker cuando los permisos permiten consultarlo; - puertos TCP en escucha, sin abrirlos ni cerrarlos; - indicadores de secretos dentro del workspace, mostrando ruta y tipo pero nunca el valor; - FTP sin cifrar, salud de credenciales de despliegue e integraciones sensibles; - disponibilidad del Docker remoto `.16` configurado por el bridge. El estado del host se actualiza en segundo plano cada quince minutos. La comprobación completa del Docker remoto solo se realiza al pulsar **Actualizar diagnóstico**. Este panel no endurece Windows, cambia firewall, rota claves ni modifica contenedores. Esas acciones necesitan un proyecto/fase de operaciones separado, copia de seguridad y autorización explícita. ## 42. Idioma El idioma principal y único habilitado actualmente es español. Ajustes contiene un selector preparado para futuros paquetes de traducción, pero no ofrece idiomas incompletos. Los nombres técnicos, identificadores de modelos, comandos y marcas pueden conservar su forma original; las explicaciones y acciones de producto se presentan en español. ## 43. Registro de integraciones por proyecto Cada workspace mantiene `.codex-suite/integrations.json` con análisis, estado, riesgo, capacidades, casos de uso y fechas. El escritor elimina campos cuyo nombre sugiera contraseña, token, secreto, API key, clave privada, autorización o cookie. Las credenciales continúan en sus almacenes protegidos y nunca se copian a este registro. Al iniciar un turno, el backend añade un resumen de las integraciones habilitadas y ordena a Codex proponerlas solo cuando aporten valor, comprobar que App Server anuncie la herramienta y mantener sandbox y aprobaciones. Cambiar de workspace cambia también el registro y evita heredar complementos o decisiones del proyecto anterior. # Router de modelos y modo Automático En **Control → Modelos**, “Comprobar catálogos” actualiza disponibilidad sin consumir inferencia. “Probar proveedores” realiza el smoke explícitamente confirmado y puede consumir cuota. Para comparar calidad en el proyecto activo: 1. Ejecuta primero el smoke de los proveedores que quieras comprobar. 2. La vista inicial muestra los modelos ya verificados, aunque su coste sea desconocido. Para explorar otros, selecciona **Todos los candidatos** y pulsa **Probar modelo** en el identificador concreto. 3. Marca entre uno y ocho modelos cuyo identificador exacto figure como verificado. 4. Pulsa **Evaluar selección en este proyecto** y confirma el consumo. 5. Revisa el ranking de calidad, coste declarado, latencia, herramientas declaradas y fiabilidad. 6. Activa **Modo Automático por proyecto** solo si quieres que las conversaciones sin modelo manual usen el ganador vigente. Los resultados son independientes por workspace. Se guardan métricas, fechas, códigos HTTP y nombres de tareas, pero no prompts, respuestas, claves ni cabeceras. Una selección manual en el compositor prevalece sobre Automático. El modelo se decide antes del turno y no cambia durante su ejecución. “Herramientas declaradas” significa que el catálogo anuncia esa capacidad; todavía no certifica una llamada real a herramientas. “Coste desconocido” no significa gratuito. ## Resiliencia, cuotas y recuperación El modo Automático mantiene salud independiente por modelo y workspace. Los fallos consecutivos aplican backoff exponencial; los HTTP 401, 402, 403 y 429 abren el circuito inmediatamente, y se respeta `Retry-After` cuando el proveedor lo envía. Mientras el circuito está abierto, el modelo queda fuera de la selección automática. Si existen alternativas evaluadas y saludables, Automático selecciona la siguiente por ranking antes de comenzar el turno. Si todas están en pausa, el backend detiene el envío y muestra la próxima prueba permitida; nunca cambia silenciosamente a un proveedor con otra política de coste o privacidad. Una selección manual sigue siendo posible bajo decisión del administrador. La recuperación solo se confirma pulsando **Volver a probar** y superando una inferencia real. El mero hecho de que un servidor acepte el inicio de un turno no se considera recuperación. ## Presupuestos y certificación de herramientas Cada workspace dispone de presupuesto diario de solicitudes para evals, máximo de modelos por ejecución y una política para permitir o bloquear modelos cuyo coste no esté verificado. El contador usa el día de `Europe/Madrid`, persiste en backend y no puede eludirse recargando la PWA. La sección **Certificación real de herramientas** lista únicamente herramientas MCP anunciadas cuyo nombre indica una operación de consulta. Se excluyen automáticamente nombres asociados a escritura, ejecución, borrado, envío, subida o despliegue. La certificación crea una conversación efímera con sandbox de solo lectura, observa una llamada real y elimina después la conversación. Guarda solamente modelo, herramienta, estado, latencia y fecha. Los nombres de marcas, modelos, plugins, MCP y herramientas permanecen sin traducir porque son identificadores técnicos. Sus estados, alcances, errores, finalidad y explicaciones se muestran en español. Los errores externos conocidos conservan también su clase técnica para diagnóstico. ## Manual avanzado interactivo El botón `?` abre el manual dentro de Codex Suite. Para esta aplicación incluye: - rutas rápidas para primeros pasos, contexto, modelos, MCP, revisión, seguridad y PWA; - búsqueda dentro de la sección actual; - índice navegable; - checklist de aprendizaje con progreso guardado localmente en el navegador; - documentación de uso y plan de producto como secciones separadas. El progreso del manual no contiene datos del proyecto ni se envía al servidor. Puede mantenerse distinto entre el iPhone y el equipo de escritorio. ## Contratos de misión y gates visuales Cada conversación puede tener un contrato independiente desde **Control → Contratos**: 1. Define el resultado esperado. 2. Limita archivos y carpetas mediante rutas relativas o patrones como `lib/**`. 3. Indica comandos de prueba obligatorios exactamente como deben observarse en el thread. 4. Añade criterios funcionales que el administrador confirmará tras revisar el resultado. 5. Selecciona el riesgo autorizado y activa el contrato. Un contrato activo se incorpora al siguiente turno. Codex recibe el objetivo, alcance, pruebas, criterios y riesgo, y no debe declarar la misión finalizada si faltan gates. Los gates son: - **Alcance de archivos**: se calcula automáticamente con el checkpoint real del turno. - **Pruebas obligatorias**: se superan únicamente cuando el thread contiene la ejecución completada con éxito del comando indicado. - **Criterios de aceptación**: requieren confirmación explícita del administrador desde la ficha del contrato. Siempre se permite rechazar cambios. La aceptación individual se deshabilita para archivos fuera de alcance; las pruebas o criterios pendientes bloquean cualquier aceptación. El backend vuelve a comprobarlo aunque se manipule el navegador. El despliegue automático solo ocurre después de una aceptación válida. ## Alternativas completas al modelo predeterminado La vista **Alternativas completas a GPT-Codex** no cambia el modelo configurado. Clasifica candidatos en tres niveles: 1. **Candidato comparable**: familia orientada a código, razonamiento y herramientas declaradas. 2. **Compatibilidad alta**: además ha superado evals de calidad del workspace. 3. **Alternativa integral certificada**: ha superado calidad y una llamada real de herramienta de consulta. Los nombres parecidos a modelos de OpenAI servidos por terceros no demuestran equivalencia. Latencia, contexto, herramientas, calidad, coste, privacidad y fiabilidad se verifican por separado. Para volver al comportamiento habitual, deja el selector del chat en Automático/predeterminado y no actives FCC para conversaciones nuevas. ## Workspace Twin · gemelo temporal del proyecto En **Control → Gemelo** se puede crear una fotografía técnica y operativa del workspace activo. Cada snapshot queda aislado por proyecto y permite comparar el estado actual con el inmediatamente anterior. El snapshot incluye: - número de archivos, carpetas y tamaño lógico observado; - extensiones y directorios principales; - stack detectado y áreas gobernadas del proyecto; - dependencias declaradas en `package.json`, `composer.json` y `requirements.txt`; - integraciones evaluadas y habilitadas; - resumen redactado de misiones y eventos del Evidence Ledger; - estado público del despliegue y su auditoría reciente; - recuento y tipo de señales de seguridad, sin incluir el valor de ningún secreto. La comparación temporal informa de archivos añadidos, retirados o modificados según ruta, tamaño y fecha de modificación; también compara dependencias y métricas operativas. No es un diff de código y no sustituye a la revisión de cambios por archivo. Protecciones aplicadas: - no se guarda el contenido de los archivos; - no se devuelven rutas absolutas; - se excluyen enlaces simbólicos, `.git`, `node_modules`, `vendor`, artefactos de compilación y almacenes internos de Codex Suite; - los manifests tienen límites de tamaño y cantidad; - se conservan como máximo veinte snapshots por workspace; - crear un snapshot exige sesión, mismo origen y confirmación exacta; - la API de consulta es de solo lectura. Si el proyecto supera 10.000 archivos observables, el snapshot se marca como truncado. En ese caso representa una vista limitada y no debe interpretarse como inventario exhaustivo. ## Preflight Staging verificable v1 **Control → Staging** prepara y comprueba una copia local de los archivos pendientes del checkpoint activo antes de aceptarlos. La operación exige sesión autenticada, mismo origen y una confirmación exacta generada por la propia interfaz. La versión 1 aplica verificadores fijos del backend: - la ruta debe permanecer dentro del workspace seleccionado; - el archivo actual debe coincidir con el estado capturado al finalizar el turno; - contenido y hash del checkpoint deben coincidir; - el conjunto no puede superar 200 archivos ni 20 MB; - los JSON deben poder analizarse; - los archivos `.js`, `.mjs` y `.cjs` deben superar `node --check`; - los patrones conocidos de claves privadas, tokens y secretos asignados se señalan sin devolver su valor. Si todo pasa, el backend materializa un paquete local marcado como `executable: false`. Su ruta interna y el contenido de los archivos no forman parte de la respuesta del navegador. El historial conserva hasta veinte informes por workspace. ### Relación con la revisión de cambios - Sin informe de preflight se conserva temporalmente la política de aceptación anterior para no romper checkpoints existentes. - Un fallo global de cantidad o tamaño bloquea cualquier aceptación del checkpoint. - Un archivo con un fallo propio queda bloqueado; otros archivos limpios todavía pueden aceptarse individualmente. - **Aceptar todo** queda bloqueado si existe cualquier incidencia. - El backend vuelve a comprobar la integridad y el informe aunque se intente alterar la interfaz. - Rechazar archivos continúa permitido. Esta versión no ejecuta comandos aportados por el navegador, tests del proyecto, compilaciones, contenedores ni despliegues. Tampoco afirma que el cambio sea funcionalmente correcto: valida condiciones estáticas y de integridad. La ejecución aislada y la promoción entre entornos pertenecen a una fase posterior. ## Security Hardening v1 El bridge comparte ahora la sesión `HttpOnly` de Codex Suite con las APIs heredadas del mismo origen. El token se introduce únicamente para crear la sesión mediante `POST /api/codex/session` o `POST /api/bridge/session`; después JavaScript no puede leer la cookie. Controles aplicados: - `/api/bootstrap` requiere autenticación y solo devuelve configuración saneada; nunca devuelve `BRIDGE_TOKEN` ni el token del supervisor; - las APIs heredadas ya no aceptan credenciales en query string ni en cuerpos genéricos; - `X-Bridge-Token` permanece temporalmente como compatibilidad para clientes existentes y scripts administrativos; - CORS solo responde al mismo origen o a valores exactos de `BRIDGE_ALLOWED_ORIGINS`; - las mutaciones rechazan orígenes ajenos y peticiones sin evidencia de mismo origen, salvo clientes heredados autenticados mediante cabecera; - `/health` es público pero mínimo; el detalle operativo requiere `/api/system/health/details` autenticado; - el Bridge principal y el lanzador eliminan tokens almacenados cuando detectan una sesión válida; - las descargas del System Manager usan cabecera o sesión, nunca tokens en URL. - el lanzador no incorpora credenciales del supervisor en enlaces locales, Tailscale ni shells móviles; cada destino protegido debe autenticar en su propio origen. En **Control → Seguridad**, la tarjeta **Security Hardening v1** muestra el estado declarado por el backend. En **Control → Pruebas** se comprueban bootstrap, tokens en URL, CORS, origen de mutaciones, health y atributos de sesión junto al resto de capas. La compatibilidad por cabecera todavía no está retirada y algunas aplicaciones vecinas antiguas pueden conservar un token introducido manualmente en `localStorage` hasta que inicien una sesión válida. Esa migración completa es trabajo posterior; el servidor ya no distribuye automáticamente esos secretos. ## Migración de sesiones v2: estado de decisión La retirada de `X-Bridge-Token` **no está implementada ni autorizada**. El análisis previo confirmó que esa cabecera no pertenece solo a Codex Suite: también interviene en aplicaciones heredadas del bridge, Telegram, herramientas de verificación y al menos un consumidor servidor externo. Retirarla o rotarla sin coordinación podría dejar funciones operativas fuera de servicio. La opción recomendada es una transición por fases: 1. inventariar propietarios y consumidores; 2. servir el bridge por HTTPS confiable; 3. usar sesiones persistentes y revocables para personas; 4. emitir credenciales independientes y limitadas para bots y servicios; 5. medir el uso heredado sin registrar secretos; 6. cortar la cabecera únicamente tras una ventana acordada con uso cero. El análisis completo, sus alternativas y las preguntas que bloquean la implementación están en [Security Hardening Review: Migración de sesiones v2](hardening/session-migration-v2/hardening.md). Hasta que se elija una opción, no existe carpeta ni plan de implementación y no debe rotarse el token desde la interfaz. ## Reconexión fiable y trabajo en varias ventanas Cada conexión de eventos recibe primero un estado técnico redactado del canal. Incluye una época distinta para cada arranque del bridge y el rango de secuencias que todavía puede reproducirse desde memoria. No contiene mensajes, prompts, respuestas ni secretos. Si una PWA vuelve después de un reinicio, o su cursor es anterior al buffer disponible, Codex Suite muestra **Recuperando estado…** y consulta de nuevo: - conversaciones y tareas activas; - runtime y aprobaciones de la conversación visible; - historial confirmado por App Server; - checkpoints y revisión de archivos; - Evidence Ledger de misiones. Esto evita que una instalación móvil quede congelada por intentar continuar una secuencia perteneciente a otro proceso. Varias ventanas pueden observar el mismo backend, pero esta versión no implementa edición colaborativa multiusuario ni resuelve escrituras humanas simultáneas. El Evidence Ledger conserva metadatos redactados. El canal SSE usa un log durable acotado (1.000 eventos) con cursor por cliente (`since` + `clientId`), política de lag y compaction anunciada (`bridge/eventLogCompacted`); ver `GET /api/codex/events/window`. La migración y deuda de seguridad aplazadas se mantienen centralizadas en [Backlog de seguridad](CODEX-SUITE-SECURITY-BACKLOG.md). ## Recuperar un turno o una compactación bloqueada Codex Suite consulta periódicamente el runtime cuando un turno deja de emitir eventos. Si la respuesta se retrasa, aparece una franja con la fase, la duración total y el tiempo transcurrido sin actividad. Una aprobación pendiente se muestra como espera del usuario y no habilita recuperación. Cuando el backend determina que el turno está obsoleto o que la compactación lleva demasiado tiempo sin actividad, aparece **Recuperar turno**. Al pulsarlo: 1. el backend solicita la interrupción a Codex App Server; 2. libera el estado activo del bridge de forma controlada; 3. compara el proyecto con el snapshot anterior al turno; 4. conserva los archivos modificados en **Revisar cambios de Codex**; 5. refresca conversación, contrato y checkpoints. La recuperación no acepta ni rechaza archivos. Revisa cada diff y usa **Aceptar archivo** o **Rechazar archivo**. La explicación situada sobre el diff es deliberadamente objetiva: indica si el archivo se creó, eliminó o modificó, su categoría aproximada y las líneas añadidas/eliminadas. No pretende adivinar la intención del cambio. Las respuestas del agente muestran, cuando está disponible, el modelo efectivo, el proveedor, el esfuerzo de razonamiento y si la selección fue automática, manual o predeterminada. Son metadatos operativos; no incluyen razonamiento privado ni credenciales. Si **Recuperar turno** no aparece, usa **Cancelar** únicamente si deseas detener un turno todavía considerado activo. La cancelación también intenta conservar los cambios detectados para revisión. ## Error boundary visual y recuperación de la interfaz Si un error de arranque o una promesa no controlada impide continuar, Codex Suite muestra un aviso accesible sobre la interfaz. El aviso presenta un resumen limitado y traducido; no muestra claves, tokens, trazas completas ni razonamiento privado. - **Cerrar aviso** oculta un error no fatal y conserva la sesión visible. - **Recargar aplicación** solicita una carga limpia del entrypoint y del grafo PWA actual. - Un error fatal de bootstrap mantiene visible la recarga y no intenta simular que el workspace está disponible. Si el aviso reaparece después de recargar, ejecuta **Control → Pruebas**, conserva la hora del incidente y revisa los logs del bridge sin copiar credenciales. La PWA v34 incluye el boundary en escritorio, móvil y modo instalado.