Corepack y packageManager: el agente usa el pnpm del repo, no el del PATH

El PATH del Mac del humano tiene un pnpm 8. El repo pide 10. El agente corre pnpm install y el lockfile “se mueve”. Corepack existe para eso: un script de Node, sin runtime deps, que intercepta yarn/pnpm/npm y baja la versión que el proyecto declaró.

README de nodejs/corepack: lets you use Yarn, npm, and pnpm without having to install them. Viene con Node 14.19.0 hasta (no incluido) 25.0.0. En 25+ hay que instalarlo a mano (npm i -g corepack) o dejar de asumir que existe.

No sustituye “pnpm only” como hábito. Es qué binario corre. El curso instalar un agente no pinnea managers.

El campo que el agente debe leer

En package.json:

{
  "packageManager": "[email protected]+sha512.abcdef…"
}

Formato: [email protected] obligatorio. Hash SHA-224 recomendado (seguridad: no te tragas un tarball distinto). Valores: yarn, npm, pnpm.

Si el proyecto está configurado para otro manager, Corepack te pide que repitas el comando con el correcto. Eso evita corromper artefactos. Si no hay campo, Corepack usa un “known good release” y el agente “sabe lo que hace” — mala idea. Pon el campo.

Enable una vez

corepack enable

Instala shims de yarn/pnpm en el PATH. El agente no hace curl | sh de pnpm ni brew install pnpm “porque no estaba”. Si corepack no existe (Node 25+ o distro mínima): reporta el bloqueo; no instales un pnpm global distinto al pin.

Al authoring: declara packageManager. Al building: usa el comando de siempre (pnpm i); Corepack cachea la versión compatible.

URL a un .js o .tgz también es válido (bin del package). YAGNI salvo forks internos.

Qué hace mal el agente

1. npm i -g pnpm@latest encima de Corepack.
2. Ignorar el error “use the right package manager”.
3. Borrar el hash “porque es largo”.
4. Asumir que el pnpm de CI es el de su laptop.

CI: corepack enable en el job antes de pnpm install --frozen-lockfile. GitHub Actions actions/setup-node tiene cache: pnpm y respeta el campo si Corepack está on.

Checklist AGENTS.md

Read packageManager in package.json.
Use that manager; do not brew/npm i -g another.
corepack enable if pnpm missing.
Never strip the integrity hash.

gitignore no cubre el binario global. Sandboxing no pinnea versiones.

FAQ

¿npm también? Sí, Corepack lo cubre. En repos pnpm, no lo uses.

¿Node 25? Corepack no va bundled. Instálalo o documenta el pin en el README del agente.

¿Sin hash? Funciona; un supply-chain swap pasa. Deja el hash.

¿Yarn Berry? El ejemplo oficial es [email protected]+sha224.…. Misma idea.

Si which pnpm apunta a ~/.local/share/pnpm y no al shim de Corepack, el agente está fuera del pin. corepack pnpm --version vs pnpm --version: si divergen, el PATH está sucio. Arregla el PATH, no el lockfile.

Verificado 2026-09-03 contra README de nodejs/corepack (enable, packageManager, Node <25).