jorgex-stack 1.9.72 → 1.9.74

package/README.md

@@ -30,6 +30,22 @@ For an installed package, skill checks are **discovery-only**: `update --check`
 
 The skill never edits artifacts or creates tasks. During audit remediation, the orchestrator is the only writer of active work artifacts and returns every gap to its owner; delegated writers still own their bounded code, test, and documentation tasks. Details: [docs/references/sdd-workflow.md](docs/references/sdd-workflow.md).
 
+### OpenCode v2: un solo runtime soportado
+
+Stack mantiene un único `opencode` v2 entre los cuatro runtimes gestionados. El ID público sigue siendo `opencode`; no se publican alias `opencode-v1`/`opencode-v2`.
+
+- **Version-gate antes de escribir.** El binario debe declarar `major === 2`. Las versiones v1, mayor desconocido, falta de binario o timeout se rechazan sin proyectar configuración, agentes, skills, MCP, plugins ni permisos en el HOME real. El gate es fail-closed.
+- **Migración owned v1 → v2.** A nivel de campos del server config y de `~/.jorgex-stack/model-map.json`, una config existente solo se migra cuando la ruta y la propiedad son exactas: los identificadores legados conocidos del canon v1 (`openai/gpt-5.6-sol`, los límites `872000/744000/128000` y los IDs dotted basados en ese modelo) se transfieren al destino nativo v2 (`openai/gpt-6.1-sol`) con backup previo. Una elección manual, un valor modificado o un campo desconocido bloquean con remedio antes de cualquier escritura. Configuración ajena, hermanos no migrables o providers no canónicos se preservan intactos o fallan cerrado; `uninstall` no borra campos ajenos y conserva providers no canónicos.
+- **`cli.json` y raíz efectiva.** El archivo compacto del cliente v2 (`cli.json`) vive junto al server config. Su raíz efectiva es `OPENCODE_CONFIG_DIR` si está definido; sin él, `$XDG_CONFIG_HOME/opencode` y, en su defecto, el default de HOME según la fuente oficial. Stack siembra `session.verbosity: "low"` solo si falta, con backup, ownership por campo y unmerge; un valor manual existente se conserva sin reclamar. Es un ajuste de presentación del TUI, no un parámetro de modelo. Mientras exista `tui.json`/`kv.json` legacy el migrador nativo del binario debe correr primero, así que Stack no precrea `cli.json`; abre OpenCode v2 una vez y repite `sync` para sembrarlo.
+- **Roster y defaults nativos.** El agente principal v2 fija `model: openai/gpt-6.1-sol`; los subagentes reciben el roster de tiers (`strong`, `standard`, `cheap`) y overrides nominales por nombre con un `model#variant` único, serializado como escalar YAML seguro. `agents.title.model` y `agents.summary.model` usan modelos distintos del principal y la compactación corre sobre el modelo de sesión, no sobre uno aparte. El `agents.plan` queda `disabled: true` (Shift+Tab no es necesario para el flujo por defecto) y el wrapper primary sigue sin lock de modelo ni de effort. Los límites explícitos son metadatos locales solicitados hasta confirmar la aceptación del backend OAuth; no se promete una ventana universal de 1 M y se advierte explícitamente de la dependencia de cuenta.
+- **Permisos canónicos v2.** El bloque nativo es un array ordenado `permissions` con tuplas `action/resource/effect`. La política canónica v2 fresh no declara gate humano (no hay `ask` para git/shell ordinarios); por eso el informe local de capabilities devuelve `tool-approval: unavailable` con razón que reconoce la política, no un estado `manual` ni un runtime certificado. Configuraciones ajenas, modificadas o ilegibles conservan una razón conservadora distinta. La regla `fresh-only` se mantiene: una config existente se preserva; el opt-in `sync/install --upgrade-permissions` reemplaza el bloque entero con backup. Detalle operativo: [docs/references/permissions.md](docs/references/permissions.md).
+- **Plugins y scripts.** Hooks, guardia de worktree y scripts de Stack viven en `stack/plugins/opencode/` y se cargan sin SDK v1. Los scripts propios OpenCode no dependen de otra instalación runtime; los plugins v1 no se reinterpretan como v2. Los **recursos estáticos** proyectados al host OpenCode (`plugins/hooks.ts`, `plugins/worktree.ts`, `scripts/post-pr-review.cjs`, `scripts/repair-worktree-config.cjs`) están listados byte-exactos en `src/lib/opencode-static-resources.json`, que acredita el canon legacy v1 publicado (no el hash actual) y cuya fila "current" se deriva de los bytes que la proyección va a escribir. Tabla única de reglas owned/unowned × current/legacy/unknown × install/update/uninstall en [docs/references/opencode-static-resources.md](docs/references/opencode-static-resources.md); aquí no se duplican.
+- **Engram v2 oficial, aún no.** Stack no ejecuta el setup oficial Engram v1 sobre OpenCode ni declara Memory Protocol completo: la integración se completa en PR04 cuando el release oficial estable posterior a Engram #1526 (o equivalente) sea verificado y adoptado. Una instalación real con ese prerrequisito ausente devuelve `exit 1` parcial: Stack proyecta y verifica primero sus archivos gestionados (los deja aplicados con manifest/backup), pero no invoca `engram setup` y conserva el binario y la DB de Engram del usuario. El caller ve el código `1` y la razón accionable; no se afirma rollback total ni setup exitoso. `sync`/`dry-run`/`--target-dir` mantienen sus skips intencionales (`ran:false`) y solo reportan el skip, no imprimen el mensaje de prerrequisito como un warning completo.
+- **Browser Control, UI y panel pendientes.** Browser Control CLI/skill/MCP, sin selector Playwright CLI, es obligatorio en v2 y se completa en PR02; el panel TUI propio y el audio se entregan en PR03. Esta guía describe el checkpoint actual, no afirma capacidades ya operativas. La política condicional de Playwright/DevTools para los demás runtimes no cambia por esta decisión.
+- **Sandbox para pruebas aisladas.** `JORGEX_OPENCODE_TARGET_MAJOR=2` solo es evidencia explícita de sandbox cuando se ejecuta junto a `--target-dir OpenCode`: el adapter ya sabe que `--target-dir` requiere esa declaración y, sin ella, no proyecta OpenCode v2 ni ejecuta el binario personal dentro del target (bloquea). En una instalación real sobre el HOME del usuario esa variable se ignora y el binario real se verifica siempre; el version-gate real lo decide el host, no Stack. No es una versión de release ni un bypass del verification real.
+
+Más detalle de permisos en [docs/references/permissions.md](docs/references/permissions.md); roster y límites en [docs/references/models.md](docs/references/models.md); estado de Browser Control en [docs/references/browser-automation.md](docs/references/browser-automation.md); reconocimiento de capabilities en [docs/references/quality-receipt.md](docs/references/quality-receipt.md); recursos estáticos proyectados y verificación byte-auth en [docs/references/opencode-static-resources.md](docs/references/opencode-static-resources.md).
+
 ## Usage
 
 Install and run via npm without cloning the repository:
@@ -63,7 +79,7 @@ For development from a clone, run the same commands through `pnpm cli <command>`
 
 Every command supports `--dry-run`, `--yes`, and `--target-dir <dir>` for testing without touching the real config. Writes create automatic backups and verify idempotency; merges into user config are surgical (marked markdown sections, JSON/TOML upserts), so user-owned content is never touched. `--yes` does not authorize downloading missing Engram; use `--engram` for that explicit consent. The interactive install asks before installing it, while dry-run and target-dir never download it.
 
-Runtime defaults are documented in [docs/references/permissions.md](docs/references/permissions.md) for permissions and [docs/references/models.md](docs/references/models.md) for the Sol primary default, field-level ownership and independent subagent routing. The quality policy and `jorgex.quality.receipt` contract are documented in [docs/references/quality-receipt.md](docs/references/quality-receipt.md). OpenCode remains provider-agnostic for subagents; its primary defaults to the OpenAI OAuth model `openai/gpt-5.6-sol` unless the user replaces it.
+Runtime defaults are documented in [docs/references/permissions.md](docs/references/permissions.md) for permissions and [docs/references/models.md](docs/references/models.md) for the Sol primary default, field-level ownership and independent subagent routing. The quality policy and `jorgex.quality.receipt` contract are documented in [docs/references/quality-receipt.md](docs/references/quality-receipt.md). OpenCode v2 sigue siendo provider-agnostic para subagentes; su agente principal fija `openai/gpt-6.1-sol` salvo que el usuario lo cambie (ver la sección OpenCode v2 arriba y la guía de modelos), y Codex/Pi conservan `gpt-5.6-sol` salvo sustitución del usuario.
 
 ### Modes: Human and Programmatic
 
@@ -91,7 +107,7 @@ Flags:
 
   This installs into all detected runtimes. To be explicit, add `--agents opencode,claude-code,codex,pi` or a comma-separated subset. Always pass `--mode programmatic`; without `--mode`, `--yes` and non-TTY installs default to `human`.
 
-  OpenCode also requires an existing selection in `~/.jorgex-stack/model-map.json`; run `pnpm dlx jorgex-stack models --agents opencode` interactively once before a headless install.
+  OpenCode v2 usa los defaults del roster aprobado en config fresca y no exige selección previa para `install --yes`, `sync` ni procesos sin TTY. Si quieres cambiar el roster o mantener una selección por agente explícita, ejecuta `pnpm dlx jorgex-stack models --agents opencode` interactivamente; las selecciones guardadas tienen precedencia sobre los defaults del roster.
 
 - `--mode human` cannot be combined with `--subagent-concurrency`.
 - Without `--mode`, the first run asks interactively; `--yes`, non-TTY, and `--target-dir` default to `human`.
@@ -153,11 +169,11 @@ Claude's official plugin still requires stable Engram 2.0.0 or newer: an existin
 
 ### Integración oficial de Engram
 
-En una instalación real, `install` delega Claude Code, Codex y OpenCode 1.x a `engram setup <runtime>` una vez por runtime durante esa instalación. Para Pi, si declara transporte nativo (`mcp-native-v1`), Stack ejecuta la fase nativa (`runNativePiMcpPhase`) y no invoca `engram setup pi`; en modo legacy Pi sigue ejecutando `engram setup pi` antes de activar el paquete. El comportamiento del provider oficial permanece sin cambios: Stack no proyecta el protocolo Engram ni filtra sus herramientas. No ejecuta ese setup durante `dry-run`, `--target-dir`, `doctor` ni `uninstall`; `install` lo invoca como parte de la reconciliación interna cuando es necesario. Stack respalda los archivos afectados, verifica los artefactos oficiales y revierte el cambio si falla; para Pi incluye `settings.json`, `mcp.json` y el árbol `npm`. No modifica `~/.engram`, sus memorias ni reemplaza un binario existente. Los artefactos oficiales se conservan al desinstalar. El `stack/plugins/opencode/engram.ts` legado ya no se despliega y queda retirado por esta integración.
+En una instalación real, `install` delega Claude Code y Codex a `engram setup <runtime>` una vez por runtime durante esa instalación. Para Pi, si declara transporte nativo (`mcp-native-v1`), Stack ejecuta la fase nativa (`runNativePiMcpPhase`) y no invoca `engram setup pi`; en modo legacy Pi sigue ejecutando `engram setup pi` antes de activar el paquete. OpenCode v2 no ejecuta `engram setup` propio: la integración oficial Engram v2 sobre OpenCode se completa en PR04 cuando un release oficial estable posterior al gate Engram #1526 (o equivalente) sea verificado y adoptado; hasta entonces Stack conserva memorias/binario y muestra el prerrequisito externo sin ejecutar setup v1 sobre el runtime. El comportamiento del provider oficial permanece sin cambios: Stack no proyecta el protocolo Engram ni filtra sus herramientas. No ejecuta ese setup durante `sync`, `dry-run`, `--target-dir`, `doctor` ni `uninstall`. Stack respalda los archivos afectados, verifica los artefactos oficiales y revierte el cambio si falla; para Pi incluye `settings.json`, `mcp.json` y el árbol `npm`. No modifica `~/.engram`, sus memorias ni reemplaza un binario existente. Los artefactos oficiales se conservan al desinstalar. El `stack/plugins/opencode/engram.ts` legado ya no se despliega y queda retirado por esta integración.
 
 Para Codex, Engram 2.0 ignora `CODEX_HOME` y escribe siempre en `$HOME/.codex`; por eso el setup oficial real requiere ese destino predeterminado. Si `CODEX_HOME` apunta a otro directorio, `install` falla cerrado en el preflight, antes de escribir la configuración de Codex, y recomienda usar `$HOME/.codex`. `dry-run` y `--target-dir` no invocan el setup oficial.
 
-La política de complementos distingue estrategias `exact` y `provider-managed`. DevTools MCP y Playwright CLI son `provider-managed`: un `install`/`update` deliberado resuelve y verifica el candidato exacto antes de activarlo, y guarda versión/integridad observadas para que `install`/`update` posteriores refresquen usando la preferencia persistida o el opt-in explícito. Las integraciones oficiales de Engram también son `provider-managed`/rolling, incluido Codex `main`, `pi-mcp-adapter` y el setup oficial de Pi sin pin en Stack. OpenCode 2 queda fuera de alcance y no bloquea esta integración.
+La política de complementos distingue estrategias `exact` y `provider-managed`. DevTools MCP y Playwright CLI son `provider-managed`: un `install`/`update` deliberado resuelve y verifica el candidato exacto antes de activarlo, y guarda versión/integridad observadas para reconciliar sin consultar al proveedor en `sync`. Las integraciones oficiales de Engram también son `provider-managed`/rolling, incluido Codex `main`, `pi-mcp-adapter` y el setup oficial de Pi sin pin en Stack. OpenCode v2 sigue su propio camino de adopción (Browser Control en PR02, Engram v2 oficial en PR04) y no bloquea la integración de los demás runtimes.
 
 Los receipts históricos, incluido `jorgex-pi@0.8.24`, son evidencia para recuperación/migración y no candidatos de instalación nuevos. La selección gestionada resuelve el `latest` publicado a una versión exacta y verifica el artefacto antes de activarlo. No edites receipts o hashes ni borres `HOME`, Engram o la proyección de otro runtime para forzar confianza. La migración y rollback están en [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
 
@@ -181,16 +197,17 @@ El paquete Pi adoptado ya no inyecta un fallback propio con `Communication Style
 
 ### Automatización de navegador
 
-La automatización de navegador es opt-in. Stack retiene el release observado en un árbol privado, no en el directorio global de pnpm. Comprueba el tarball npm oficial y el cierre transitivo instalado en un stage aislado, promociona ese árbol con receipt y verifica launcher y árbol antes de las ejecuciones gestionadas. Un `playwright-cli` global o una invocación `pnpm dlx` **no** ofrecen esa garantía y nunca son fallback. La caché del navegador pertenece a Playwright; uninstall y update no borran perfiles, cookies, storage state, trazas ni capturas.
+La automatización de navegador es opt-in. Stack retiene el release observado en un árbol privado, no en el directorio global de pnpm. Comprueba el tarball npm oficial y el cierre transitivo instalado en un stage aislado, promociona ese árbol con receipt y verifica launcher y árbol antes de las ejecuciones gestionadas. Un `playwright-cli` global o una invocación `pnpm dlx` **no** ofrecen esa garantía y nunca son fallback. La caché del navegador pertenece a Playwright; uninstall y update no borran perfiles, cookies, storage state, trazas ni capturas. La integración gestionada de Browser Control para OpenCode v2 se entregará en el siguiente checkpoint y será obligatoria (CLI, skill y MCP). Este checkpoint todavía acepta `--playwright-runtimes=opencode`. Solo el servicio relay Linux será opt-in; la política de otros runtimes no cambia.
 
-- **Playwright CLI** (recomendado): `install --playwright` selecciona el último release estable del proveedor en ese momento, verifica el árbol gestionado, descarga Chromium desde ese árbol y comprueba un arranque headless local de `about:blank` antes de guardar el opt-in. Úsalo mediante `jorgex-stack browser playwright <args>` (o el dispatcher empaquetado `jorgex-stack-playwright` para el handoff Pi confiable), no mediante un binario global. Usa una sesión `-s=<nombre>` propia, `snapshot`, comprueba resultados y cierra solo tu sesión.
+- **Playwright CLI** (recomendado para los runtimes que aún lo admiten): `install --playwright` selecciona el último release estable del proveedor en ese momento, verifica el árbol gestionado, descarga Chromium desde ese árbol y comprueba un arranque headless local de `about:blank` antes de guardar el opt-in. Úsalo mediante `jorgex-stack browser playwright <args>` (o el dispatcher empaquetado `jorgex-stack-playwright` para el handoff Pi confiable), no mediante un binario global. Usa una sesión `-s=<nombre>` propia, `snapshot`, comprueba resultados y cierra solo tu sesión.
 - **Chrome DevTools MCP** (diagnóstico avanzado): desactivado por defecto y seleccionado por runtime. Stack usa launcher local verificado y conserva `--isolated --redact-network-headers --no-performance-crux --no-usage-statistics`. La redacción de cabeceras no cubre los cuerpos request/response; evita sesiones sensibles. Esta integración no descarga Chrome.
 - **Pi**: el paquete compatible publicado acepta un handoff Playwright v2 con SHA del dispatcher Stack, launcher y árbol. Stack lo proyecta solo con receipt browser verificado, selección explícita y declaración `contract/browser-handoffs.v1.json` del Pi instalado; un Pi antiguo sin ella bloquea v2/v3 sin deducir soporte por versión. El lector v1 permanece para receipts antiguos, no como fallback nuevo. En Windows Pi ejecuta el `.js` autenticado con Node sin shell. DevTools v3 también es byte-bound.
 
 ```bash
 # Interactivo: el cursor Playwright parte en No.
 pnpm dlx jorgex-stack install
-# Opt-in no interactivo explícito para los runtimes de archivo seleccionados.
+# Opt-in no interactivo explícito (la lista de runtimes `--playwright-runtimes` sigue
+# aceptando `opencode`; el camino real para OpenCode v2 será Browser Control en PR02).
 pnpm dlx jorgex-stack install --yes --playwright --playwright-runtimes=opencode,claude-code
 # Ejecución gestionada tras la activación.
 jorgex-stack browser playwright -s=mi-tarea open --browser=chromium https://example.com