Git worktrees + hoisted pnpm: where did my binaries go?

I run parallel coding agents in git worktrees — each variant gets an isolated checkout, nobody steps on anybody. First surprise: inside a worktree, pnpm check explodes because eslint, vitest and next don't exist.

Obvious in hindsight: a worktree shares the repository, not the working directory. It's a fresh checkout of tracked files — and node_modules is not a tracked file. With .npmrc saying node-linker=hoisted, every dependency and every .bin shim lives in one flat node_modules at the original repo root. The worktree has your source and none of your tools.

Two mitigations, both used depending on the job:

• Install in the worktree when the agent genuinely needs to run the full toolchain there. Costs time and disk per worktree (the lockfile is already resolved, so it's pnpm install --frozen-lockfile — cached, but not free).
• Gate on the main checkout instead. Agents run what works without binaries (e.g. tsc via the shared root, or nothing), and the authoritative lint + typecheck + test + build runs after merge, on the real checkout — where node_modules actually exists. A failed gate there is still reversible with one revert.

Bonus gotcha from the same setup: git worktree add bases the new branch on whatever you give it — agents that assume "current branch" quietly base off the wrong one, and agents that bare-cd around leak commands into the parent checkout. Address worktrees explicitly (git -C <path>) and pass the base branch every time.

Seedling because the ergonomics are still evolving — but the root cause is now a law: worktrees isolate files, not installations.