# Codex Suite · Análisis sync IDE / Composer ↔ Suite

> Corte: **9 de agosto de 2026**. Documento de análisis previo a la implementación v1 premium.
> Fuente de verdad de producto: [CODEX-SUITE-STATUS.md](CODEX-SUITE-STATUS.md) · roadmap [CODEX-SUITE-ROADMAP.md](CODEX-SUITE-ROADMAP.md) §1.6.

## 1. Objetivo

Lograr **continuidad local fiable** entre Cursor IDE (Agent / Composer con espejo JSONL) y Codex Suite:

1. Continuar desde Suite cualquier conversación con `agent-transcripts` del workspace.
2. Si se inicia un chat Cursor nuevo desde Suite, que aparezca en el IDE tras **Desarrollador: Recargar ventana** / reabrir el chat.
3. Si se continúa en Suite un chat ya iniciado, el JSONL se actualiza y el IDE lo ve tras reload.
4. Composer: investigar e integrar solo lo **seguro**; índice privado operador para metadatos SQLite.

## 2. Alcance / no-alcance

| Incluido v1 | Excluido |
|-------------|----------|
| Sync durable vía `agent-transcripts` + Cursor SDK | Escritura a `state.vscdb` / `bubbleId` |
| Binding canónico `agentId` + `transcriptPath` | Sync en caliente del panel Composer |
| Append enriquecido de turnos Suite | Import cloud Cursor |
| Picker unificado IDE UUID + SDK `agent-*` | WhatsApp / correo / app consumidor final |
| Índice Composer **read-only** gated (`CODEX_COMPOSER_PRIVATE`) | Productizar el store privado de Cursor |

**Principio comercial:** el producto vendible se apoya en transcripts + SDK + UX Suite. El índice Composer queda **operador-only** hasta API oficial.

## 3. Arquitectura actual vs deseada

### 3.1 Actual (parcial)

```
Suite ──list──► agent-transcripts (UUID + agent-*)
Suite ──turns──► Cursor SDK (create/resume)
Suite ──append?─► JSONL solo si hay transcriptPath (a menudo falta en chat nuevo)
Composer UI ◄── state.vscdb (no usado por Suite)
```

### 3.2 Deseada v1

```
Suite ──newChat──► createNewIdeConversation (UUID JSONL)
Suite ──bind─────► storage/codex-conversation-bindings.json
Suite ──turn─────► Agent.resume|create + append JSONL (siempre)
IDE ◄──reload──── agent-transcripts actualizado
Operador (flag) ─read──► composerHeaders ⨝ UUID transcripts
```

## 4. Hallazgos verificados (PC operador)

| Canal | Ubicación | Rol |
|-------|-----------|-----|
| Agent JSONL | `%USERPROFILE%\.cursor\projects\<slug>\agent-transcripts\<id>\<id>.jsonl` | Canónico Suite |
| Cursor SDK | `@cursor/sdk` Agent.create/resume/list | Ejecución |
| Composer SQLite | `%APPDATA%\Cursor\User\globalStorage\state.vscdb` (~10 GB) | UI nativa; solo lectura privada |
| Overlap | Mismos UUID a menudo en `composerHeaders` y transcripts | Este chat `5cebb22a-…` existe en ambos |

Gaps P0 previos a v1:

1. Suite no fuerza `newChat` → sin JSONL UUID → invisible en IDE.
2. UUID IDE: no `Agent.resume` nativo → contexto truncado + agente nuevo.
3. Append solo texto plano con prefijos móvil.
4. Binding repartido (`codex-cursor-sessions`, `sdk-sessions`) sin contrato único.
5. Composer-only sin JSONL: invisible al producto.

## 5. Matriz de comprobaciones

| ID | Caso | Esperado v1 |
|----|------|-------------|
| C1 | Listar sources workspace bridge | IDE + SDK cwd; binding si existe |
| C2 | Continuar transcript UUID desde Suite | Turno OK; append en JSONL; agentId guardado |
| C3 | Chat Cursor nuevo desde Suite | `createNewIdeConversation`; path en done; binding |
| C4 | Tras C3: reload ventana IDE | Chat listable / reabrible |
| C5 | Continuar SDK `agent-*` | resume; espejo JSONL si falta |
| C6 | Tools/diffs en Suite | Timeline SSE (no requisito de paridad en JSONL IDE) |
| C7 | Composer index sin flag | 404/oculto |
| C8 | Composer index con flag | Metadatos + join transcript; sin escritura vscdb |
| C9 | Entitlement plan_required | Mensaje claro; no simular sync |

## 6. Riesgos

- **Entitlement**: `CURSOR_API_KEY` Free vs IDE Pro → 402/403.
- **WAL SQLite**: lectura `state.vscdb` con Cursor abierto puede fallar.
- **Schema `_v`**: Composer muta sin contrato; no escribir.
- **slugToPath / espacios**: usar workspace index.
- **Reload**: no hay push al panel abierto; documentar UX.

## 7. Criterios de aceptación premium v1

- [x] Binding durable por workspace/thread.
- [x] Todo turno Cursor Suite con texto hace append a un transcriptPath válido.
- [x] Chat nuevo Suite crea UUID bajo el slug del proyecto.
- [x] Picker muestra IDE primero y SDK recientes del cwd.
- [x] UX indica “Recargar ventana / reabrir chat” para ver en IDE.
- [x] Tests automatizados de append + binding + newChat.
- [x] Docs STATUS/ROADMAP/MANUAL alineados.
- [x] Composer privado gated; cero escritura vscdb.

## 8. Checklist implementación

1. Doc (este archivo) + canvas + README/STATUS/ROADMAP.
2. Store bindings + wiring routes/UI/server.
3. Enriquecer `transcript-append`.
4. Tests + smoke.
5. Fase 2 Composer read-only.

## 9. Referencias de código

- `lib/conversations.js` — list/create transcripts  
- `lib/transcript-append.js` — append  
- `lib/agent-runner.js` — SDK  
- `lib/codex-cursor-routes.js` — API Suite  
- `lib/codex-cursor-sessions.js` — historial motor por thread  
- `server.js` — `runChatJob`  
- `static/codex-suite/modules/chat.js` — UI