[lucasbraum]

What and why

On a repository whose package.json pins "packageManager": "yarn@4.x" (any Yarn 2 or later) while the global yarn is classic 1.x, or there is none, uptide fix and uptide verify failed to install: Yarn stopped with "This project's package.json defines packageManager yarn@4.7.0. However the current global version of Yarn is 1.22.22". The same failure the pack-test job had on tldraw's ground truth (#53), fixed there with corepack in CI.

The installer used by fix and verify (packages/core/src/fix/managers/availability.ts) now:

• Detects a pinned Yarn 2+ that the yarn on PATH cannot run: classic 1.x, another version than the pin, or no yarn at all (needsCorepack). A Berry on PATH at the pinned version is used as before.
• Runs it through corepack when corepack is available: the same install as corepack yarn install --immutable --mode=skip-build, with COREPACK_ENABLE_DOWNLOAD_PROMPT=0 and COREPACK_ENABLE_AUTO_PIN=0 (throughCorepack). Nothing on the user's machine changes outside corepack's own cache: no corepack enable, no shim, no rewrite of packageManager. Every later install in the run (updateArgs, the plain install) goes through the same route (PackageManager.via).
• Exits 2 before cloning when corepack is missing (PACKAGE_MANAGER_UNAVAILABLE, raised by run.ts before any clone), with the exact command:

  This repository pins yarn@4.7.0 (packageManager), but the yarn on PATH is 1.22.22 and corepack is not available to run the pinned version. Nothing was cloned or installed.
  Next: corepack enable
  

• Respects COREPACK_NPM_REGISTRY from the environment (it passes through to the corepack call as it is) and names it only when corepack could not fetch the pinned version, together with the manual activation command.

docs/troubleshooting.md gains "Yarn 4 says the global Yarn is 1.x", and the "Package manager not available" section points to it. packs/tooling/truth.ts (ground-truth installs for pack test) is unchanged; CI handles that with corepack enable since #53.

How it was verified

Unit tests in availability.test.ts, against a new fixture fixtures/repos/yarn-berry-pinned (synthetic: pins yarn@4.7.0, Berry lockfile, node-modules linker, nothing installed):

• detection: pinned Berry with no yarn, with classic 1.22.22, with Berry 4.6.0 → corepack; with Berry 4.7.0 → not; classic and pnpm repositories → never;
• command selection: corepack yarn install --immutable --mode=skip-build, prompt off, via: 'corepack', updateArgs prefixed with yarn;
• the probe sequence (yarn --version, corepack --version, corepack yarn --version) and that corepack enable is never run;
• corepack missing → exit-2 error with Next: corepack enable; corepack unable to fetch → message with COREPACK_NPM_REGISTRY and the activation command (and the registry hint absent when corepack is simply missing); a corepack yarn at the wrong version → PACKAGE_MANAGER_VERSION.

pnpm lint, pnpm typecheck, pnpm docs:links, the private-material guard, core (928 tests) and CLI (350 tests) pass. One unrelated test (check/progress.test.ts, worker-event forwarding) failed once while the suite shared the machine with the build, and passed three times in isolation.

Checklist

• Tests for the change (a bug fix starts with a failing test)
• pnpm lint && pnpm typecheck && pnpm test pass
• README and docs updated if behavior changed
• Changeset added if a user would notice (pnpm changeset): patch
• No new dependency, or it was agreed in an issue
• No private code, names or paths in fixtures, tests or docs
• The rules in CONTRIBUTING.md ("Rules that do not bend") still hold

🤖 Generated with Claude Code

https://claude.ai/code/session_018u9b3Pp5H68DdYZGp5Qg1U

---

Generated by Claude Code