jorgex-stack 1.9.61 → 1.9.63

package/README.md

@@ -48,7 +48,7 @@ For a fresh Engram installation, always consult the current published Stack and
 pnpm --config.dlx-cache-max-age=0 dlx jorgex-stack@latest install --engram
 ```
 
-`dlx-cache-max-age` is separate from the pnpm 11 dependency-age filter: it controls only the cached `dlx` package, while `minimumReleaseAgeExclude` applies only to the named package resolution. An explicit Stack version such as `@1.9.30` does not reuse the cache entry for another version. Do not use `@latest` for Pi; Pi consumption still requires its exact validated pin.
+`dlx-cache-max-age` is separate from the pnpm 11 dependency-age filter: it controls only the cached `dlx` package, while `minimumReleaseAgeExclude` applies only to the named package resolution. An explicit Stack version such as `@1.9.30` does not reuse the cache entry for another version. Pi `install`/`update` resolve the registry's observed published `latest` dist-tag to an exact version and verify the artifact before activation; they do not install a floating `latest` alias.
 
 Other important commands:
 
@@ -114,9 +114,9 @@ Programmatic mode does **not** provide:
 
 ### Pi runtime
 
-El canon de Stack y el paquete Pi adoptado mantienen una snapshot de 17 árboles de skills con 89 archivos de skill. La identidad, procedencia e integridad del paquete adoptado son autoritativas en `src/lib/pi-runtime-pin.json`.
+El canon de Stack y el paquete Pi mantienen una snapshot de 17 árboles de skills con 89 archivos de skill. Para instalaciones deliberadas, Stack resuelve la versión publicada observada en npm y verifica el tarball y el stage; `src/lib/pi-runtime-pin.json` y el historial conservan identidades congeladas, no un selector para futuras instalaciones.
 
-Pi combines the frozen **snapshot v2** package with a Stack-owned shared projection. The current pin is the published `jorgex-pi@0.8.28` artifact. Package identity, integrity and lifecycle are maintained in [docs/references/pi-runtime.md](docs/references/pi-runtime.md) and `src/lib/pi-runtime-pin.json`; this README does not duplicate mutable pin metadata.
+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.
 
 The following command block is retained as historical reference for that transition:
 
@@ -128,9 +128,11 @@ pnpm dlx jorgex-stack@1.9.7 sync --agents pi
 pnpm dlx jorgex-stack@1.9.7 uninstall --agents pi
 ```
 
-For the current Pi `0.8.28` pin, package identity and runner validation precede projection; the exact pending initialization diagnostic remains provisional until projection and final `sync` complete.
+For a deliberate managed install or update, Stack resolves the live published `latest` tag to an exact release, verifies its canonical tarball URL and SRI/bytes, and prepares it in an isolated stage before activation. The stage locks six dependencies and runs smoke checks; Stack then backs up state and publishes only its owned package entry. Automatic restoration covers activation/verification failures; a later projection or sync failure may need manual recovery from the retained backup. The schema 1 receipt records managed-package evidence for offline verification. `sync`, `models`, `doctor` and `uninstall` do not acquire a new version; they require an authenticated receipt/artifact, with explicit legacy recovery paths where applicable. `update --check` does not download. `--target-dir` neither downloads Pi nor touches the real HOME; with a previously verified candidate/stage injected, it can run isolated smoke/runner code inside the target. Direct Pi installation is separate and does not provide Stack's rollback guarantees.
 
-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`, `mcp.json` and provider-owned `npm` tree, and restores the backup on setup failure; Pi is not activated unless setup and subsequent package lifecycle succeed. The exact artifact and integrity values are authoritative in `src/lib/pi-runtime-pin.json`, while the lifecycle remains authoritative in `src/lib/pi-runtime.ts`. 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 global Playwright package and Chromium cache are shared by the machine; `--playwright-runtimes` controls which runtime receives the guide. The adopted Pi package implements and tests `playwright-handoff-v1` through `PI_CODING_AGENT_DIR/jorgex-pi/playwright.v1.json`. 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 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`, `mcp.json` and provider-owned `npm` tree, and restores the backup on setup failure; Pi is not activated unless setup and subsequent package lifecycle succeed. 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,11 +158,11 @@ En una instalación real, `install` delega Claude Code, Codex y OpenCode 1.x a `
 
 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.
 
-La política de complementos distingue estrategias `exact` y `provider-managed`. DevTools MCP y Playwright CLI mantienen pins exactos; las integraciones oficiales de Engram 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 2 queda fuera de alcance y no bloquea esta integración.
 
-Históricamente, Stack `1.9.7` reconocía el receipt exacto de Pi `npm:jorgex-pi@0.8.4`. Usa versiones exactas, nunca `latest`, y no edites receipts o hashes ni borres `HOME`, Engram o la proyección de otro runtime para forzar confianza. El pin y los comandos actuales de transición y rollback están en [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
+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).
 
-Pi puede consumirse inmediatamente después de publicar y verificar el artefacto adoptado. El pin exacto, la procedencia, los SHA-256/SHA-512, el SRI, la compatibilidad y el procedimiento de rollback siguen siendo obligatorios; no uses `latest` ni una versión aproximada.
+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` only runs the Pi package lifecycle; it does not enter the global Stack updater. `update --check --agents pi` performs a read-only check of the Pi package and local registration metadata through the package runner. It does not compare Stack's projection, run the browser smoke check, or mutate Pi state; use `doctor --agents pi` for the complete package-and-projection diagnosis. Uninstall runs package cleanup, backs up Pi's settings before removal, removes only the exact receipt-owned package after verifying absence, and preserves all companion/user state. Full behavior, failure states and troubleshooting are in [docs/references/pi-runtime.md](docs/references/pi-runtime.md).
 
@@ -172,41 +174,28 @@ La proyección contiene el canon directamente: Stack no añade un wrapper adicio
 
 El paquete Pi adoptado ya no inyecta un fallback propio con `Communication Style` en español; el estilo de escritura que recibe Pi procede de la proyección gestionada por Stack.
 
-### Browser automation
-
-Browser automation is opt-in and explicit. The legacy `agent-browser` integration and the vendored Playwright skill have been removed; the shared CLI remains available through the global tool flow.
+### Automatización de navegador
 
-- **Playwright CLI** (recommended): the global package `@playwright/cli@0.1.18`, shared by the machine and enabled explicitly. The conditional browser guide tells agents to open Chromium with `--browser=chromium`, consult `playwright-cli --help`, use a task-specific session, take a `snapshot`, verify results and close only sessions they created. See [docs/references/browser-automation.md](docs/references/browser-automation.md) for the lifecycle, privacy profile and troubleshooting.
-- **Chrome DevTools MCP** (advanced diagnostics, opt-in): exposes ~29 tools and ~5,800–7,700 tokens of schemas in full mode. Disabled by default, selected per runtime, version-pinned, and launched with a fixed argv `pnpm dlx chrome-devtools-mcp@1.6.0 --isolated --redact-network-headers --no-performance-crux --no-usage-statistics`. `--isolated` starts Chrome with an ephemeral, isolated profile that is deleted when Chrome closes (no persistent dedicated profile, no shared cookies/extensions/sessions with your personal Chrome); `--redact-network-headers` redacts sensitive headers in captured network traffic, but not request/response bodies, which may contain tokens or PII. Avoid authenticated sessions or sensitive data, or disable network capture manually outside the stack when needed. `--no-performance-crux` disables CrUX reporting; `--no-usage-statistics` disables telemetry. `--slim` and Playwright MCP are intentionally excluded.
+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.
 
-Setup that respects the zero-secrets, pnpm-only and explicit-consent rules:
+- **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.
+- **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
-# Interactive (TTY): the install prompt suggests Playwright CLI but defaults to "No" (opt-in consent). Press `y` to install.
+# Interactivo: el cursor Playwright parte en No.
 pnpm dlx jorgex-stack install
-
-# Non-interactive / agent: --playwright authorizes the global install.
-pnpm dlx jorgex-stack install --yes --playwright
-
-# Instala el paquete compartido y activa la guía solo en estos runtimes.
-pnpm dlx jorgex-stack install --playwright --playwright-runtimes=opencode,claude-code
-
-# Enable Chrome DevTools MCP explicitly per runtime.
+# Opt-in no interactivo explícito para los runtimes de archivo seleccionados.
+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
+jorgex-stack browser playwright -s=mi-tarea snapshot
+jorgex-stack browser playwright -s=mi-tarea close
+# DevTools es independiente y opcional.
 pnpm dlx jorgex-stack install --devtools
-pnpm dlx jorgex-stack install --no-devtools
-pnpm dlx jorgex-stack install --agents pi --devtools
-pnpm dlx jorgex-stack sync --agents pi --no-devtools
 ```
 
-Under the hood, `--playwright` runs two `pnpm` argv-only plans back to back: `pnpm add --global @playwright/cli@0.1.18` (the package) and then `pnpm dlx @playwright/cli@0.1.18 install-browser chromium` (the Chromium cache). It then verifies that the pinned package launches Chromium headless against `about:blank`. Removal is `pnpm remove --global @playwright/cli` (no version suffix). If installation fails, the error identifies the failed phase — global package, browser download, browser launch, or preference persistence — and recommends `jorgex-stack install --playwright`; the preference is not marked enabled unless the complete plan succeeds.
-
-Daily operation:
-
-- `sync` reconciles configuration without installing global tools or browsers; if Playwright is enabled but the binary or browser cache is `missing`, it warns and points to `install --playwright`; if the cache is `unreadable`, the warning includes its resolved path and filesystem error code. If the local Chromium launch check fails, `sync` removes the projected Playwright guide, preserves the enabled preference, and points to `install --playwright` for repair. The cache probe retains the path for both states and an error code when the filesystem provides one. Under `--target-dir`, `sync`/`install`/`uninstall` never read or write the real browser state (`~/.jorgex-stack/playwright-cli.json` and `~/.jorgex-stack/devtools-mcp.json` are untouched, `detectPlaywrightCli()` is not called, no MCP ownership is persisted).
-- `doctor` reports the Playwright CLI state (`disabled`, `healthy`, `missing:package`, `missing:browser`, `unreadable`, `broken`, `outdated`) and, when the opt-in package and browser cache are present, verifies one local headless Chromium launch against `about:blank`; it does not open external sites or repair state. An `unreadable` browser cache includes its exact path and filesystem error code so permissions or another local cause can be investigated. If either preference file is corrupt, doctor prints the exact path and the remedy (`Corrige o borra ese archivo antes de reintentar`) before any other browser check; in that case `install`/`uninstall`/`update`/`update --check` will abort with exit 1 until the file is fixed, so the corruption cannot be reconciled destructively.
-- `update --check` only inspects Playwright CLI when its preference is `enabled` (a binary appearing in `PATH` is not consent). It compares the installed version against the approved pin `0.1.18` — it does not consult npm latest, and a Playwright CLI binary-only update does not require `sync` afterwards.
-- `uninstall` preserves the global `@playwright/cli` package and all browser data by default; `--remove-playwright` removes the package only (never the browser cache, profiles, cookies, storage state, traces, screenshots or videos). If `pnpm remove --global @playwright/cli` exits non-zero, `uninstall` reports the failure instead of a success outro. For DevTools MCP, ownership is released only after the corresponding unmerge is applied; if no unmerge action is written, the ownership marker is preserved for a later retry.
-- `install`/`sync` also inject (and `disable`/`uninstall` remove) managed capability sections in `AGENTS.md` (OpenCode, Codex) or `CLAUDE.md` (Claude Code). File runtimes keep `jorgex:playwright`, `jorgex:chrome-devtools` and `jorgex:context7` independent; Pi 0.8.28 projects Context7 after registering its isolated HTTP bridge. Stack does not add an Engram protocol section or filter provider tools. User content outside managed markers is preserved. `--target-dir` never reads the real preferences, so by default no section is emitted in target-dir runs — but explicit flags like `--devtools` simulate the MCP entry (and its DevTools block) inside the temp target without touching the real global state, and `install --dry-run --playwright` projects the Playwright section into the plan preview without installing anything. If reconciliation detects a partial or ambiguous system-prompt state, the CLI exits non-zero and recommends repairing it with `sync` or a repeated install; no write is attempted before marker validation. See [docs/references/browser-automation.md](docs/references/browser-automation.md) §2.7 for the full lifecycle.
+`sync` revalida el receipt local sin resolver ni descargar paquetes browser y retira la guía si el estado gestionado falla. `doctor` revisa receipt, versión, caché Chromium y arranque headless local sin reparar. `update --check` observa solo estado local; `install` o `update` interactivo deliberados pueden adquirir un nuevo release verificado. `uninstall` conserva por defecto el árbol gestionado y los datos del navegador; `--remove-playwright` desactiva preferencia y guía con backup, sin retirar un CLI global ajeno. Una preferencia ilegible bloquea mutaciones y `doctor` señala su ruta. Con `--target-dir` Stack no toca el estado browser del HOME real. Consulta [automatización de navegador](docs/references/browser-automation.md) para receipts, reparación y handoffs Pi.
 
 ### Update: Interactive Flow
 
@@ -214,7 +203,7 @@ Daily operation:
 
 1. **Stack** (jorgex-stack): detects whether it is a git clone or a global install, then offers an update with confirmation.
 2. **Engram** (binary): detects the installed version and offers an update through the **native channel** only with explicit confirmation. The database and memories are never touched, and Stack does not replace an existing binary as part of runtime setup.
-3. **Playwright CLI** (only when explicitly enabled): compares the detected binary with the approved bundle pin and offers to realign it with explicit confirmation. The realignment re-applies **both** plans — `pnpm add --global @playwright/cli@0.1.18` (package) and `pnpm dlx @playwright/cli@0.1.18 install-browser chromium` (Chromium cache) — and fails closed if either step returns non-zero. The error identifies whether the package-update or browser-download phase failed and recommends `jorgex-stack install --playwright` to retry both; a Playwright update does not require `sync`.
+3. **Playwright CLI** (solo si se habilitó explícitamente): compara el receipt local autenticado con la observación guardada, muestra el drift del proveedor en el selector interactivo y exige una segunda confirmación. Prepara y verifica el release seleccionado, promociona el árbol gestionado y comprueba Chromium; no actualiza ni elimina un CLI global.
 4. **Vendored skills** (maintainer only): third-party skills ship **pinned** with the stack version, so the installed package never reaches out to their upstreams. Only when running from a git clone (`pnpm cli update`) does `update` scan the upstreams in `upstreams.json`, download to a temp directory, **show a mandatory diff**, and ask for confirmation. A moved upstream is only a candidate until that review is accepted and a deliberate re-pin is made for a future release; it is never treated as an accepted official update automatically. Skills with local changes (`modified: true`) warn and require double confirmation.
 
 Usage:

package/dist/browser-playwright.d.ts

@@ -0,0 +1,2 @@
+
+export {  }