jorgex-stack 1.9.67 → 1.9.69

package/README.md

@@ -118,7 +118,7 @@ El canon de Stack y el paquete Pi mantienen una snapshot de 17 árboles de skill
 
 Pi combines the **snapshot v2** package with a Stack-owned shared projection. Package resolution, verification, receipt and recovery behavior are documented in [docs/references/pi-runtime.md](docs/references/pi-runtime.md); historical pins are not a promise that personal Pi installations have migrated.
 
-En Pi nuevo, Stack gestiona `jorgex-pi` y sus seis companions locales, y prepara los providers oficiales `gentle-engram` y `pi-mcp-adapter` en stages Pi-native aislados. Cada `install` o `update` deliberado resuelve el `latest` publicado, verifica lock/SRI/árbol y promociona solo los dos directorios provider; conserva el enlace y receipt privados de `jorgex-pi`, el host Pi, las entradas npm ajenas y los datos de Engram. Con un receipt Stack válido, `install --agents pi` continúa por la actualización autenticada; el estado manual o ambiguo se bloquea. El [inventario de Pi](docs/references/pi-runtime.md#inventario-operativo-de-pi) distingue componentes obligatorios y opcionales.
+En Pi nuevo, Stack gestiona `jorgex-pi` y sus seis companions locales, y prepara el provider oficial `gentle-engram` en un stage aislado. Cuando el candidato Pi verificado declara el contrato nativo `mcp-native-v1`, `install` o `update` deliberado ejecuta la fase nativa (`runNativePiMcpPhase`) antes de la promoción del paquete: `mcp.json` pasa a ser la autoridad persistente de los servidores protegidos (`engram`, `context7`, `chrome-devtools`), no se instala `pi-mcp-adapter` y la autoridad granular vive en `pi-projection-receipt.json`. La fase nativa solo **prepara** (`NativeMcpPreparedWrite` con `created`/`removals`/`snapshot`/`backupRoot`); el handoff activo y `mcp.json` los escribe el ciclo de proyección (`runPiProjectionLifecycleSystem`), que aplica el handoff DevTools v3 contra la estampa `receipt.devtools.sha256` y, después del readback, invoca una sola vez `pendingNativeConfigWrite` (CAS de remociones y crements con `restoreOwnedWrite`); sólo entonces publica el receipt y la autoridad final. Cada `install` o `update` deliberado resuelve el `latest` publicado, verifica lock/SRI/árbol y promociona solo el provider gentle en modo nativo (o los dos providers en modo legacy); conserva el enlace y receipt privados de `jorgex-pi`, el host Pi, las entradas npm ajenas y los datos de Engram. Con un receipt Stack válido, `install --agents pi` continúa por la actualización autenticada; el estado manual o ambiguo se bloquea. El [inventario de Pi](docs/references/pi-runtime.md#inventario-operativo-de-pi) distingue componentes obligatorios y opcionales, y la sección de [transporte nativo y autoridad granular](docs/references/pi-runtime.md#transporte-nativo-y-autoridad-granular) describe el contrato nativo verificable (no se infiere por versión del host ni por `testedVersions`); el opt-out explícito de DevTools retira el claim de la autoridad y, cuando la entrada sigue full-stamped, el `mcp.json` la elimina; cuando está personalizada la conserva y queda UNOWNED (no se reclama de vuelta por SHA idéntico y exige resolución manual).
 
 The following command block is retained as historical reference for that transition:
 
@@ -134,7 +134,7 @@ For a deliberate managed install or update, Stack resolves the live published `l
 
 The artifact values in `src/lib/pi-runtime-pin.json` describe frozen historical/reference metadata, not the live install candidate; live artifact URL, version and integrity are resolved from the published registry.
 
-Stack runs provider-owned `engram setup pi` before Pi package activation on a real managed install. It backs up and verifies Pi's `settings.json`, both possible MCP config paths (`mcp.json` and `mcp-adapter.json`) and the provider-owned `npm` tree, and restores the backup on setup failure; Pi is not activated unless setup and subsequent package lifecycle succeed. The effective MCP path comes from the installed `pi-mcp-adapter` metadata: major 2 reads `mcp.json`, while major 3+ reads `mcp-adapter.json`; missing metadata fails closed instead of falling back. A duplicate official Engram root in the legacy path is a conflict, not a healthy configuration. The runtime lifecycle remains authoritative in `src/lib/pi-runtime.ts`; the exact release evidence belongs to the verified receipt and tarball. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. A managed install then runs provider setup, `package install → projection install → package sync`. Stack projects shared resources such as the system prompt, canonical skills and `lean-audit`; it does not inject `jorgex:engram-protocol`, project Engram tools, or filter provider tools. The behavioral `engram` role remains part of the Pi contract, while the official provider owns its setup and tools. Pi registers Context7 through an isolated in-memory HTTP bridge during bootstrap; `available` means configuration permits registration and does not imply an HTTP handshake. A conflict preserves the existing MCP file and blocks managed activation. No MCP credentials are written. For the file runtimes, Context7, Playwright and DevTools use independent managed sections. The managed Playwright tree belongs to Stack while Chromium’s cache is shared by the machine; `--playwright-runtimes` controls which runtime receives the guide. The published compatible Pi reader accepts a byte-bound Playwright v2 handoff; its v1 reader remains for historical receipts, not new opt-ins. Stack projects v2 only after its managed browser receipt and Pi package pass verification, including `contract/browser-handoffs.v1.json`; an older Pi without that declaration blocks new v2/v3 handoffs without a version-number guess. Package ownership is recorded separately in `~/.jorgex-stack/pi-receipt.json`; projection ownership is recorded in `~/.jorgex-stack/pi-projection-receipt.json`. Package receipts reject manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state. Projection cleanup requires an exact scope-bound ownership receipt; DevTools conflicts preserve the handoff for review.
+Stack runs provider-owned `engram setup pi` before Pi package activation on a real managed install when the candidate does not declare native transport; for a candidate that declares `mcp-native-v1`, Stack runs `runNativePiMcpPhase` instead and does not invoke the official setup. The legacy branch backs up and verifies Pi's `settings.json`, both possible MCP config paths (`mcp.json` and `mcp-adapter.json`) and the provider-owned `npm` tree, and restores the backup on setup failure; Pi is not activated unless setup and subsequent package lifecycle succeed. The effective MCP path comes from the installed `pi-mcp-adapter` metadata: major 2 reads `mcp.json`, while major 3+ reads `mcp-adapter.json`; missing metadata fails closed instead of falling back. A duplicate official Engram root in the legacy path is a conflict, not a healthy configuration. The native branch keeps `mcp.json` as the persistent authority for the three protected servers, stamps the granular `mcpNative` authority in `pi-projection-receipt.json`, and uses `beforeInitialization`/`beforePackageDeactivation` against the actual installed module before the internal sync and before the private package is deactivated. The runtime lifecycle remains authoritative in `src/lib/pi-runtime.ts`; the exact release evidence belongs to the verified receipt and tarball. Pi's own package-manager invocation is the narrow runtime exception to the repository's pnpm-only rule; the Stack lifecycle never launches npm directly. A managed install then runs provider setup, `package install → projection install → package sync`. Stack projects shared resources such as the system prompt, canonical skills and `lean-audit`; it does not inject `jorgex:engram-protocol`, project Engram tools, or filter provider tools. The behavioral `engram` role remains part of the Pi contract, while the official provider owns its setup and tools. Pi registers Context7 through an isolated in-memory HTTP bridge during bootstrap; `available` means configuration permits registration and does not imply an HTTP handshake. A conflict preserves the existing MCP file and blocks managed activation. No MCP credentials are written. For the file runtimes, Context7, Playwright and DevTools use independent managed sections. The managed Playwright tree belongs to Stack while Chromium’s cache is shared by the machine; `--playwright-runtimes` controls which runtime receives the guide. The published compatible Pi reader accepts a byte-bound Playwright v2 handoff; its v1 reader remains for historical receipts, not new opt-ins. Stack projects v2 only after its managed browser receipt and Pi package pass verification, including `contract/browser-handoffs.v1.json`; an older Pi without that declaration blocks new v2/v3 handoffs without a version-number guess. Package ownership is recorded separately in `~/.jorgex-stack/pi-receipt.json`; projection ownership is recorded in `~/.jorgex-stack/pi-projection-receipt.json`. Package receipts reject manual, duplicate, divergent, partial, corrupt, copied-to-another-scope, or unknown-history state. Projection cleanup requires an exact scope-bound ownership receipt; DevTools conflicts preserve the handoff for review.
 
 The static `AGENTS.md` projected by Stack does not include Context7; Pi's native bootstrap adds that section after registering the isolated bridge. Pi never writes, owns or removes MCP files. In Claude Code, Codex and OpenCode, a compatible existing Context7 entry is preserved and removed only with explicit canonical Stack ownership. During package installation only, `initialization-diagnostics-v1` permits the exact pending `doctor` envelope described in [the Pi runtime reference](docs/references/pi-runtime.md); it is provisional and does not make Pi healthy. Projection and final `sync` must still complete, and every other unhealthy or malformed result remains blocked.
 
@@ -156,7 +156,7 @@ 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, y Pi ejecuta `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 `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.
+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 `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`. `sync`, `dry-run` y `--target-dir` no invocan el setup oficial.
 
@@ -166,7 +166,13 @@ Los receipts históricos, incluido `jorgex-pi@0.8.24`, son evidencia para recupe
 
 Stack gestiona la selección dinámica y verificación de Pi en `install`/`update`; esto no significa que una instalación personal de Pi se haya migrado. La automatización Stack ↔ Pi es snapshot-only. La instalación directa de Pi no incluye la etapa aislada ni el rollback de Stack.
 
-`update --agents pi` cambia versiones deliberadamente: resuelve y verifica el paquete Pi y los dos providers oficiales en stages aislados, aplica la promoción acotada y verifica la configuración MCP. No entra en el updater global de Stack, no actualiza el host Pi ni toca los datos de Engram. `sync --agents pi` reaplica la proyección a partir del paquete autenticado y comprueba el estado MCP existente; no resuelve versiones ni descarga providers. `update --check --agents pi` consulta el runner sin mutar Pi; `doctor --agents pi` diagnostica paquete y proyección. Uninstall respalda los settings y retira solo el paquete exacto acreditado por el receipt, verificando su ausencia y conservando companions y estado ajeno. Consulta los límites de recuperación en la [referencia Pi](docs/references/pi-runtime.md).
+`update --agents pi` cambia versiones deliberadamente: resuelve y verifica el paquete Pi y los providers oficiales en stages aislados (con candidato nativo solo `gentle-engram`; con candidato legacy también `pi-mcp-adapter`), aplica la promoción acotada y verifica la configuración MCP. No entra en el updater global de Stack, no actualiza el host Pi ni toca los datos de Engram. `sync --agents pi` reaplica la proyección a partir del paquete autenticado y comprueba el estado MCP existente; no resuelve versiones ni descarga providers. `update --check --agents pi` consulta el runner sin mutar Pi; `doctor --agents pi` diagnostica paquete y proyección. Uninstall respalda los settings y retira solo el paquete exacto acreditado por el receipt, verificando su ausencia y conservando companions y estado ajeno. En modo nativo, `uninstall` corre la comprobación activa de ownership contra el módulo Pi realmente instalado antes de desactivar el paquete privado y respeta la autoridad granular `mcpNative` para decidir qué entradas retira. Consulta los límites de recuperación en la [referencia Pi](docs/references/pi-runtime.md).
+
+### Variante temporal del provider y recibo separado (candidato, devtool)
+
+> **Candidato / devtool — todavía no publicado en npm.** Mientras la corrección upstream `#1567` de `gentle-engram` no se publique, `--engram-typebox-compat` extiende la fase nativa del padre (PR203), ya importada como base, bajo la misma política de input/receipt de la flag candidata verificada y sin duplicar authority, config ni cardinality nativos. El caller nativo del padre (`runNativePiMcpPhase` y sus receipts análogos) no se reutiliza aquí como updater; el candidato no lo sustituye. Esta sección no declara Windows, MCP nativo, autorización personal, instalación nativa fresca, publicación ni aplicación personal como verificadas. La variante descrita es un artefacto local derivado —no es un fork ni un release npm— que aplica sólo el diff de `#1567` sobre bytes oficiales verificados, registra su procedencia en un recibo separado y se retira cuando el release oficial corregido se active como `registry`.
+
+`--engram-typebox-compat` es un booleano explícito; cuando no se pasa, la propiedad queda **realmente ausente** (`undefined`) y no se conserva ninguna preferencia ni se añaden campos obligatorios a flags/fixtures. Sólo se acepta en `install` y `update` deliberados cuyo `--agents` incluya `pi` y **sin** combinar con `--dry-run` ni `--target-dir`; `update --check`, `--dry-run` y `--target-dir` (en `install` o `update`), `sync`, `models`, `doctor`, `uninstall` e `install` sin `pi` rechazan el flag antes de cualquier efecto. `--dry-run` y `--target-dir` siguen sin adquirir providers ni escribir estado personal. Stack registra la procedencia de `gentle-engram` y `pi-mcp-adapter` en `<home>/.jorgex-stack/pi-provider-receipt.json` (schemaVersion 1), un archivo distinto del `pi-receipt.json` del paquete JorgeX Pi y de la autoridad MCP. El campo `provenance` es **opcional** ligado a la adquisición `#1567`-compat: cuando el oficial ya viene corregido el builder devuelve `provenance.origin = "registry"`; mientras no, devuelve `provenance.origin = "derived"`; en ambos casos se descarta el `path` de stage y se conserva el payload original del manifiesto como `manifestBase64` (texto base64 que decodifica al manifiesto bounded —el límite aplica al payload decodificado, no al string literal) junto con su digest y la referencia del patch para verificación offline. Es procedencia local reproducible, no attestation independiente del publisher. `doctor` lee este recibo y diferencia `registry` vs `derived`; no consulta la red, no repara y nunca presenta un error como setup sano. Una `update` deliberada sobre derivado existente conserva la receta sin volver a requerir el flag, sólo si el recibo verificado lo permite; no se autosiembran preferencias y ningún otro comando propaga el opt-in. Las garantías de transacción (backup, idempotencia, rollback, detección de modificaciones ajenas con reporte de `recovery incomplete`), la retirada tras activación verificada del oficial corregido y la advertencia de que operaciones fuera de la transacción gestionada de Stack (comandos manuales, removedores externos, updater nativo de Pi en modo manual) pueden sustituir o degradar los bytes del provider —y que el verificador detecta ese drift sin ser una ACL— se describen en [la referencia Pi](docs/references/pi-runtime.md#variante-temporal-del-provider-y-recibo-separado-candidato-devtool). El updater de providers de **Stack** (función) opera sólo sobre el **transporte legacy**; el transporte nativo lo maneja la **fase nativa del padre** (PR203, `runNativePiMcpPhase`) con la misma política de opt-in y snapshot, sin duplicar la autoridad nativa. Un recibo nativo aún no publicado no debe presentarse como instalación nativa sana; este candidato no declara Windows, cohorte público, publicación npm ni aplicación personal como verificados. La autoridad MCP nativo, el set nativo y la cardinalidad de la cohorte pública pertenecen a PR203; este contrato no los duplica ni los anticipa.
 
 ### Estilo global de escritura
 

package/dist/cli.d.ts

@@ -28,6 +28,8 @@ interface Flags {
     devtools: boolean;
     noDevtools: boolean;
     upgradePermissions: boolean;
+    /** Opt-in explícito a la variante temporal #1567 solo en install/update con Pi. */
+    engramTypeboxCompat?: boolean;
     receipt?: string;
     positional: string[];
     unknownFlags: string[];